@claudetools/tools 0.3.9 → 0.5.0

package/dist/helpers/usage-analytics.d.ts

@@ -0,0 +1,91 @@
+export interface UsageEvent {
+    timestamp: string;
+    operation: 'generate_api' | 'generate_frontend' | 'generate_component' | 'validate_spec';
+    generator?: string;
+    framework?: string;
+    entityName?: string;
+    fieldCount?: number;
+    specLength?: number;
+    filesGenerated?: number;
+    linesOfCode?: number;
+    tokensSaved?: number;
+    options?: {
+        auth?: boolean;
+        validation?: boolean;
+        tests?: boolean;
+        database?: string;
+    };
+    success: boolean;
+    executionTimeMs?: number;
+    projectId?: string;
+}
+export declare class UsageAnalytics {
+    private static instance;
+    private constructor();
+    static getInstance(): UsageAnalytics;
+    /**
+     * Track a successful generation
+     */
+    trackGeneration(event: Omit<UsageEvent, 'timestamp' | 'success'>): Promise<void>;
+    /**
+     * Track a validation
+     */
+    trackValidation(spec: string, valid: boolean, entityName?: string, fieldCount?: number, projectId?: string): Promise<void>;
+}
+export declare const analytics: UsageAnalytics;
+/**
+ * Analytics query interface
+ */
+export interface AnalyticsQuery {
+    startTime: string;
+    endTime: string;
+    operation?: UsageEvent['operation'];
+    generator?: string;
+    framework?: string;
+}
+export interface AnalyticsResult {
+    totalGenerations: number;
+    totalTokensSaved: number;
+    avgTokensSavedPerGeneration: number;
+    totalLinesOfCode: number;
+    totalFiles: number;
+    generatorStats: Record<string, {
+        count: number;
+        tokensSaved: number;
+        linesOfCode: number;
+        filesGenerated: number;
+    }>;
+    frameworkStats: Record<string, number>;
+    optionsUsage: {
+        auth: number;
+        validation: number;
+        tests: number;
+    };
+    entityPatterns: Record<string, number>;
+    avgExecutionTime?: number;
+    recentGenerations: UsageEvent[];
+}
+/**
+ * Query usage analytics
+ */
+export declare function getUsageAnalytics(query: AnalyticsQuery): Promise<AnalyticsResult>;
+/**
+ * Get analytics for last 24 hours
+ */
+export declare function getLast24HoursAnalytics(): Promise<AnalyticsResult>;
+/**
+ * Get analytics for last 7 days
+ */
+export declare function getLast7DaysAnalytics(): Promise<AnalyticsResult>;
+/**
+ * Get analytics for last 30 days
+ */
+export declare function getLast30DaysAnalytics(): Promise<AnalyticsResult>;
+/**
+ * Print analytics report
+ */
+export declare function printAnalytics(result: AnalyticsResult, title?: string): void;
+/**
+ * Weekly analytics summary
+ */
+export declare function weeklyAnalyticsSummary(): Promise<void>;

package/dist/helpers/usage-analytics.js

@@ -0,0 +1,256 @@
+// =============================================================================
+// CodeDNA Usage Analytics
+// =============================================================================
+//
+// Track CodeDNA usage patterns, token savings, and generator popularity
+// for analytics and optimization insights.
+//
+import { storeFact, searchMemory } from './api-client.js';
+import { DEFAULT_USER_ID, resolveProjectId } from './config.js';
+export class UsageAnalytics {
+    static instance;
+    constructor() { }
+    static getInstance() {
+        if (!UsageAnalytics.instance) {
+            UsageAnalytics.instance = new UsageAnalytics();
+        }
+        return UsageAnalytics.instance;
+    }
+    /**
+     * Track a successful generation
+     */
+    async trackGeneration(event) {
+        try {
+            const usageEvent = {
+                ...event,
+                timestamp: new Date().toISOString(),
+                success: true,
+            };
+            const userId = DEFAULT_USER_ID;
+            const projectId = event.projectId || resolveProjectId();
+            // Store as fact in memory system
+            await storeFact(projectId, 'CodeDNA', 'GENERATION_COMPLETED', event.generator || event.operation, JSON.stringify(usageEvent), userId);
+            console.log('[CodeDNA Analytics]', {
+                operation: event.operation,
+                generator: event.generator,
+                tokensSaved: event.tokensSaved,
+            });
+        }
+        catch (error) {
+            // Don't fail the operation if analytics fails
+            console.error('[CodeDNA Analytics Failed]', error);
+        }
+    }
+    /**
+     * Track a validation
+     */
+    async trackValidation(spec, valid, entityName, fieldCount, projectId) {
+        await this.trackGeneration({
+            operation: 'validate_spec',
+            entityName,
+            fieldCount,
+            specLength: spec.length,
+            success: valid,
+            projectId,
+        });
+    }
+}
+// Export singleton instance
+export const analytics = UsageAnalytics.getInstance();
+/**
+ * Query usage analytics
+ */
+export async function getUsageAnalytics(query) {
+    const userId = DEFAULT_USER_ID;
+    const projectId = resolveProjectId();
+    // Search for usage facts
+    const searchQuery = `CodeDNA GENERATION_COMPLETED ${query.operation || ''}`;
+    const result = await searchMemory(projectId, searchQuery, 500, userId);
+    // Parse usage events from facts
+    const events = result.relevant_facts
+        .map((fact) => {
+        try {
+            return JSON.parse(fact.fact);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter((e) => e !== null)
+        .filter((e) => {
+        const eventTime = new Date(e.timestamp).getTime();
+        const start = new Date(query.startTime).getTime();
+        const end = new Date(query.endTime).getTime();
+        return eventTime >= start && eventTime <= end;
+    })
+        .filter((e) => !query.operation || e.operation === query.operation)
+        .filter((e) => !query.generator || e.generator === query.generator)
+        .filter((e) => !query.framework || e.framework === query.framework);
+    // Calculate statistics
+    const totalTokensSaved = events.reduce((sum, e) => sum + (e.tokensSaved || 0), 0);
+    const totalLinesOfCode = events.reduce((sum, e) => sum + (e.linesOfCode || 0), 0);
+    const totalFiles = events.reduce((sum, e) => sum + (e.filesGenerated || 0), 0);
+    // Generator statistics
+    const generatorStats = {};
+    events.forEach(event => {
+        const gen = event.generator || 'unknown';
+        if (!generatorStats[gen]) {
+            generatorStats[gen] = { count: 0, tokensSaved: 0, linesOfCode: 0, filesGenerated: 0 };
+        }
+        generatorStats[gen].count++;
+        generatorStats[gen].tokensSaved += event.tokensSaved || 0;
+        generatorStats[gen].linesOfCode += event.linesOfCode || 0;
+        generatorStats[gen].filesGenerated += event.filesGenerated || 0;
+    });
+    // Framework statistics
+    const frameworkStats = {};
+    events.forEach(event => {
+        if (event.framework) {
+            frameworkStats[event.framework] = (frameworkStats[event.framework] || 0) + 1;
+        }
+    });
+    // Options usage
+    let authCount = 0;
+    let validationCount = 0;
+    let testsCount = 0;
+    events.forEach(event => {
+        if (event.options?.auth)
+            authCount++;
+        if (event.options?.validation)
+            validationCount++;
+        if (event.options?.tests)
+            testsCount++;
+    });
+    // Entity patterns
+    const entityPatterns = {};
+    events.forEach(event => {
+        if (event.entityName) {
+            entityPatterns[event.entityName] = (entityPatterns[event.entityName] || 0) + 1;
+        }
+    });
+    // Average execution time
+    const executionTimes = events.filter(e => e.executionTimeMs).map(e => e.executionTimeMs);
+    const avgExecutionTime = executionTimes.length > 0
+        ? executionTimes.reduce((sum, t) => sum + t, 0) / executionTimes.length
+        : undefined;
+    return {
+        totalGenerations: events.length,
+        totalTokensSaved,
+        avgTokensSavedPerGeneration: events.length > 0 ? totalTokensSaved / events.length : 0,
+        totalLinesOfCode,
+        totalFiles,
+        generatorStats,
+        frameworkStats,
+        optionsUsage: {
+            auth: authCount,
+            validation: validationCount,
+            tests: testsCount,
+        },
+        entityPatterns,
+        avgExecutionTime,
+        recentGenerations: events.slice(0, 10).reverse(),
+    };
+}
+/**
+ * Get analytics for last 24 hours
+ */
+export async function getLast24HoursAnalytics() {
+    const endTime = new Date().toISOString();
+    const startTime = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+    return getUsageAnalytics({ startTime, endTime });
+}
+/**
+ * Get analytics for last 7 days
+ */
+export async function getLast7DaysAnalytics() {
+    const endTime = new Date().toISOString();
+    const startTime = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+    return getUsageAnalytics({ startTime, endTime });
+}
+/**
+ * Get analytics for last 30 days
+ */
+export async function getLast30DaysAnalytics() {
+    const endTime = new Date().toISOString();
+    const startTime = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString();
+    return getUsageAnalytics({ startTime, endTime });
+}
+/**
+ * Print analytics report
+ */
+export function printAnalytics(result, title = 'CodeDNA Usage Analytics') {
+    console.log('\n=================================================');
+    console.log(title);
+    console.log('=================================================\n');
+    console.log('Overview:');
+    console.log(`  Total Generations: ${result.totalGenerations}`);
+    console.log(`  Total Tokens Saved: ${result.totalTokensSaved.toLocaleString()}`);
+    console.log(`  Avg Tokens/Generation: ${Math.round(result.avgTokensSavedPerGeneration).toLocaleString()}`);
+    console.log(`  Total Lines of Code: ${result.totalLinesOfCode.toLocaleString()}`);
+    console.log(`  Total Files Generated: ${result.totalFiles}`);
+    if (result.avgExecutionTime) {
+        console.log(`  Avg Execution Time: ${Math.round(result.avgExecutionTime)}ms`);
+    }
+    console.log();
+    if (Object.keys(result.generatorStats).length > 0) {
+        console.log('Generator Usage:');
+        Object.entries(result.generatorStats)
+            .sort((a, b) => b[1].count - a[1].count)
+            .forEach(([gen, stats]) => {
+            console.log(`  ${gen}:`);
+            console.log(`    Count: ${stats.count}`);
+            console.log(`    Tokens Saved: ${stats.tokensSaved.toLocaleString()}`);
+            console.log(`    Lines of Code: ${stats.linesOfCode.toLocaleString()}`);
+            console.log(`    Files Generated: ${stats.filesGenerated}`);
+        });
+        console.log();
+    }
+    if (Object.keys(result.frameworkStats).length > 0) {
+        console.log('Framework Popularity:');
+        Object.entries(result.frameworkStats)
+            .sort((a, b) => b[1] - a[1])
+            .forEach(([framework, count]) => {
+            console.log(`  ${framework}: ${count} generations`);
+        });
+        console.log();
+    }
+    console.log('Options Usage:');
+    console.log(`  Auth: ${result.optionsUsage.auth} generations`);
+    console.log(`  Validation: ${result.optionsUsage.validation} generations`);
+    console.log(`  Tests: ${result.optionsUsage.tests} generations`);
+    console.log();
+    if (Object.keys(result.entityPatterns).length > 0) {
+        console.log('Popular Entities:');
+        Object.entries(result.entityPatterns)
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .forEach(([entity, count]) => {
+            console.log(`  ${entity}: ${count} times`);
+        });
+        console.log();
+    }
+    if (result.recentGenerations.length > 0) {
+        console.log('Recent Generations:');
+        result.recentGenerations.forEach((gen, i) => {
+            console.log(`  ${i + 1}. [${gen.timestamp}] ${gen.operation}`);
+            console.log(`     Generator: ${gen.generator || 'N/A'}`);
+            console.log(`     Entity: ${gen.entityName || 'N/A'}`);
+            console.log(`     Tokens Saved: ${(gen.tokensSaved || 0).toLocaleString()}`);
+        });
+    }
+    console.log('\n=================================================\n');
+}
+/**
+ * Weekly analytics summary
+ */
+export async function weeklyAnalyticsSummary() {
+    console.log('Generating weekly CodeDNA analytics summary...\n');
+    const result = await getLast7DaysAnalytics();
+    printAnalytics(result, 'CodeDNA Weekly Analytics Summary');
+    // Calculate ROI
+    const estimatedCost = result.totalTokensSaved * 0.00001; // ~$0.01 per 1000 tokens
+    console.log('💰 Estimated Cost Savings:');
+    console.log(`   Traditional approach: $${estimatedCost.toFixed(2)}`);
+    console.log(`   With CodeDNA: $${(estimatedCost * 0.01).toFixed(2)} (99% savings)`);
+    console.log(`   Total saved: $${(estimatedCost * 0.99).toFixed(2)}\n`);
+}

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/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