@claudetools/tools 0.5.2 → 0.6.0

package/dist/handlers/codedna-handlers.d.ts

@@ -4,12 +4,35 @@
 export declare function handleGenerateApi(args: any): Promise<{
     error: string;
     details: string[] | undefined;
-    message?: undefined;
     supported?: undefined;
     success?: undefined;
     files?: undefined;
     metadata?: undefined;
     tokenSavings?: undefined;
+    message?: undefined;
+} | {
+    error: string;
+    supported: string[];
+    details?: undefined;
+    success?: undefined;
+    files?: undefined;
+    metadata?: undefined;
+    tokenSavings?: undefined;
+    message?: undefined;
+} | {
+    success: boolean;
+    files: Record<string, string>;
+    metadata: import("../codedna/types.js").GenerationMetadata;
+    tokenSavings: {
+        traditional: number;
+        codedna: number;
+        saved: number;
+        percentSaved: string;
+    };
+    error?: undefined;
+    details?: undefined;
+    supported?: undefined;
+    message?: undefined;
 } | {
     error: string;
     message: string;
@@ -19,15 +42,28 @@ export declare function handleGenerateApi(args: any): Promise<{
     files?: undefined;
     metadata?: undefined;
     tokenSavings?: undefined;
+}>;
+/**
+ * Handle codedna_generate_frontend tool call
+ */
+export declare function handleGenerateFrontend(args: any): Promise<{
+    error: string;
+    details: string[] | undefined;
+    supported?: undefined;
+    success?: undefined;
+    files?: undefined;
+    metadata?: undefined;
+    tokenSavings?: undefined;
+    message?: undefined;
 } | {
     error: string;
     supported: string[];
     details?: undefined;
-    message?: undefined;
     success?: undefined;
     files?: undefined;
     metadata?: undefined;
     tokenSavings?: undefined;
+    message?: undefined;
 } | {
     success: boolean;
     files: Record<string, string>;
@@ -40,24 +76,17 @@ export declare function handleGenerateApi(args: any): Promise<{
     };
     error?: undefined;
     details?: undefined;
-    message?: undefined;
     supported?: undefined;
-}>;
-/**
- * Handle codedna_generate_frontend tool call
- */
-export declare function handleGenerateFrontend(args: any): Promise<{
-    error: string;
-    details: string[] | undefined;
     message?: undefined;
-    frameworks?: undefined;
-    status?: undefined;
 } | {
     error: string;
     message: string;
-    frameworks: string[];
-    status: string;
     details?: undefined;
+    supported?: undefined;
+    success?: undefined;
+    files?: undefined;
+    metadata?: undefined;
+    tokenSavings?: undefined;
 }>;
 /**
  * Handle codedna_generate_component tool call
@@ -65,17 +94,44 @@ export declare function handleGenerateFrontend(args: any): Promise<{
 export declare function handleGenerateComponent(args: any): Promise<{
     error: string;
     details: string[] | undefined;
+    supported?: undefined;
+    success?: undefined;
+    files?: undefined;
+    metadata?: undefined;
+    tokenSavings?: undefined;
+    message?: undefined;
+} | {
+    error: string;
+    supported: string[];
+    details?: undefined;
+    success?: undefined;
+    files?: undefined;
+    metadata?: undefined;
+    tokenSavings?: undefined;
+    message?: undefined;
+} | {
+    success: boolean;
+    files: Record<string, string>;
+    metadata: import("../codedna/types.js").GenerationMetadata;
+    tokenSavings: {
+        traditional: number;
+        codedna: number;
+        saved: number;
+        percentSaved: string;
+    };
+    error?: undefined;
+    details?: undefined;
+    supported?: undefined;
     message?: undefined;
-    types?: undefined;
-    frameworks?: undefined;
-    status?: undefined;
 } | {
     error: string;
     message: string;
-    types: string[];
-    frameworks: string[];
-    status: string;
     details?: undefined;
+    supported?: undefined;
+    success?: undefined;
+    files?: undefined;
+    metadata?: undefined;
+    tokenSavings?: undefined;
 }>;
 /**
  * Handle codedna_list_generators tool call

package/dist/handlers/codedna-handlers.js

@@ -8,6 +8,11 @@
 import { validateSpec } from '../codedna/parser.js';
 import { TemplateRegistry } from '../codedna/registry.js';
 import { ExpressApiGenerator } from '../codedna/generators/express-api.js';
+import { FastAPIGenerator } from '../codedna/generators/fastapi-api.js';
+import { NestJSGenerator } from '../codedna/generators/nestjs-api.js';
+import { ReactFrontendGenerator } from '../codedna/generators/react-frontend.js';
+import { VueFrontendGenerator } from '../codedna/generators/vue-frontend.js';
+import { UIComponentGenerator } from '../codedna/generators/ui-component.js';
 import { errorTracker } from '../helpers/error-tracking.js';
 import { analytics } from '../helpers/usage-analytics.js';
 // Singleton registry instance
@@ -33,16 +38,10 @@ export async function handleGenerateApi(args) {
         generator = new ExpressApiGenerator(registry);
     }
     else if (framework === 'fastapi') {
-        return {
-            error: 'FastAPI generator not yet implemented',
-            message: 'Currently only Express is supported. Coming soon: FastAPI, NestJS',
-        };
+        generator = new FastAPIGenerator(registry);
     }
     else if (framework === 'nestjs') {
-        return {
-            error: 'NestJS generator not yet implemented',
-            message: 'Currently only Express is supported. Coming soon: FastAPI, NestJS',
-        };
+        generator = new NestJSGenerator(registry);
     }
     else {
         return {
@@ -103,13 +102,58 @@ export async function handleGenerateFrontend(args) {
             details: validation.errors,
         };
     }
-    // Frontend generators not yet implemented
-    return {
-        error: 'Frontend generators not yet implemented',
-        message: 'Coming soon: Next.js, React, Vue frontend generation',
-        frameworks: ['nextjs', 'react', 'vue'],
-        status: 'planned',
-    };
+    // Select generator based on framework
+    let generator;
+    if (framework === 'nextjs' || framework === 'react') {
+        generator = new ReactFrontendGenerator(registry);
+    }
+    else if (framework === 'vue') {
+        generator = new VueFrontendGenerator(registry);
+    }
+    else {
+        return {
+            error: `Unsupported framework: ${framework}`,
+            supported: ['nextjs', 'react', 'vue'],
+        };
+    }
+    try {
+        const startTime = Date.now();
+        // Generate code
+        const result = await generator.generate(validation.parsed, options);
+        const executionTime = Date.now() - startTime;
+        // Track successful generation
+        await analytics.trackGeneration({
+            operation: 'generate_frontend',
+            generator: `${framework}-frontend`,
+            framework,
+            entityName: validation.parsed.name,
+            fieldCount: validation.parsed.fields.length,
+            specLength: spec.length,
+            filesGenerated: result.metadata.filesGenerated,
+            linesOfCode: result.metadata.linesOfCode,
+            tokensSaved: result.metadata.estimatedTokensSaved,
+            options: options,
+            executionTimeMs: executionTime,
+        });
+        return {
+            success: true,
+            files: result.files,
+            metadata: result.metadata,
+            tokenSavings: {
+                traditional: result.metadata.linesOfCode * 25,
+                codedna: 150,
+                saved: result.metadata.estimatedTokensSaved,
+                percentSaved: ((result.metadata.estimatedTokensSaved / (result.metadata.linesOfCode * 25)) * 100).toFixed(1) + '%',
+            },
+        };
+    }
+    catch (error) {
+        await errorTracker.trackGenerationError(framework, spec, error instanceof Error ? error : new Error(String(error)));
+        return {
+            error: 'Code generation failed',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
 }
 /**
  * Handle codedna_generate_component tool call
@@ -124,14 +168,59 @@ export async function handleGenerateComponent(args) {
             details: validation.errors,
         };
     }
-    // Component generators not yet implemented
-    return {
-        error: 'Component generators not yet implemented',
-        message: 'Coming soon: Form, Table, Card, Modal components',
-        types: ['form', 'table', 'card', 'modal'],
-        frameworks: ['react', 'vue', 'svelte'],
-        status: 'planned',
-    };
+    // Validate component type
+    const validTypes = ['form', 'table', 'card', 'modal'];
+    if (!validTypes.includes(type)) {
+        return {
+            error: `Invalid component type: ${type}`,
+            supported: validTypes,
+        };
+    }
+    // Validate framework
+    const validFrameworks = ['react', 'vue', 'svelte'];
+    if (!validFrameworks.includes(framework)) {
+        return {
+            error: `Invalid framework: ${framework}`,
+            supported: validFrameworks,
+        };
+    }
+    try {
+        const startTime = Date.now();
+        const generator = new UIComponentGenerator(registry, type, framework);
+        const result = await generator.generate(validation.parsed, options);
+        const executionTime = Date.now() - startTime;
+        await analytics.trackGeneration({
+            operation: 'generate_component',
+            generator: `${framework}-${type}`,
+            framework,
+            entityName: validation.parsed.name,
+            fieldCount: validation.parsed.fields.length,
+            specLength: spec.length,
+            filesGenerated: result.metadata.filesGenerated,
+            linesOfCode: result.metadata.linesOfCode,
+            tokensSaved: result.metadata.estimatedTokensSaved,
+            options: options,
+            executionTimeMs: executionTime,
+        });
+        return {
+            success: true,
+            files: result.files,
+            metadata: result.metadata,
+            tokenSavings: {
+                traditional: result.metadata.linesOfCode * 25,
+                codedna: 100,
+                saved: result.metadata.estimatedTokensSaved,
+                percentSaved: ((result.metadata.estimatedTokensSaved / (result.metadata.linesOfCode * 25)) * 100).toFixed(1) + '%',
+            },
+        };
+    }
+    catch (error) {
+        await errorTracker.trackGenerationError(`${framework}-${type}`, spec, error instanceof Error ? error : new Error(String(error)));
+        return {
+            error: 'Component generation failed',
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
 }
 /**
  * Handle codedna_list_generators tool call

package/dist/handlers/tool-handlers.js

@@ -4,7 +4,8 @@
 import { CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { mcpLogger } from '../logger.js';
 import { getDefaultProjectId, DEFAULT_USER_ID, lastContextUsed, setLastContextUsed, API_BASE_URL } from '../helpers/config.js';
-import { EXPERT_WORKERS, matchTaskToWorker } from '../helpers/workers.js';
+import { EXPERT_WORKERS, matchTaskToWorker, buildWorkerPrompt } from '../helpers/workers.js';
+import { validateTaskDescription } from '../templates/orchestrator-prompt.js';
 import { searchMemory, addMemory, storeFact, getContext, getSummary, getEntities, injectContext, apiRequest, listCachedDocs, getCachedDocs, cacheDocs } from '../helpers/api-client.js';
 import { queryDependencies, analyzeImpact } from '../helpers/dependencies.js';
 import { checkPatterns } from '../helpers/patterns.js';
@@ -432,8 +433,20 @@ export function registerToolHandlers(server) {
                     });
                     const epic = epicResult.data;
                     const createdTasks = [];
+                    // Track description validation warnings
+                    const descriptionWarnings = [];
                     // Create each task under the epic with worker assignment
                     for (const taskDef of tasks) {
+                        // Validate task description doesn't contain code (orchestrators should delegate, not implement)
+                        if (taskDef.description) {
+                            const validation = validateTaskDescription(taskDef.description);
+                            if (!validation.valid) {
+                                descriptionWarnings.push({
+                                    task: taskDef.title,
+                                    warnings: validation.warnings,
+                                });
+                            }
+                        }
                         // Match task to expert worker
                         const worker = matchTaskToWorker({
                             title: taskDef.title,
@@ -541,21 +554,60 @@ export function registerToolHandlers(server) {
                         const worker = EXPERT_WORKERS[workerId];
                         output += `- **${worker.name}**: ${items.length} task(s)\n`;
                     }
+                    // Show warnings if task descriptions contained code (orchestrator anti-pattern)
+                    if (descriptionWarnings.length > 0) {
+                        output += `\n## ⚠️ Task Description Warnings\n\n`;
+                        output += `**Best Practice:** Task descriptions should define WHAT and WHY, not HOW.\n`;
+                        output += `Orchestrators should delegate implementation details to worker agents.\n\n`;
+                        for (const warning of descriptionWarnings) {
+                            output += `**${warning.task}:**\n`;
+                            for (const w of warning.warnings) {
+                                output += `  - ${w}\n`;
+                            }
+                        }
+                        output += `\n**Tip:** For entities, use DSL format: "User(email:string:unique, password:string:hashed)"\n`;
+                        output += `Workers will use CodeDNA to generate code automatically.\n`;
+                    }
                     // Auto-dispatch section with exact Task tool invocations
                     output += `\n---\n\n`;
                     output += `## Auto-Dispatch: Spawn Parallel Agents Now\n\n`;
                     output += `**IMPORTANT:** Execute these Task tool calls in a SINGLE message to spawn parallel workers:\n\n`;
                     output += `\`\`\`\n`;
                     for (const dt of dispatchable) {
-                        // Build a concise but complete prompt for the agent
-                        const taskPrompt = [
-                            `Execute task ${dt.task.id}: ${dt.task.title}`,
-                            dt.task.description ? `\nDescription: ${dt.task.description}` : '',
-                            `\nEpic: ${epic.title}`,
-                            `\nGoal: ${goal}`,
-                            `\nWhen complete, call task_complete(task_id="${dt.task.id}", summary="...") with a summary of work done.`,
-                        ].filter(Boolean).join('');
-                        output += `Task(subagent_type="general-purpose", prompt="${taskPrompt.replace(/"/g, '\\"')}")\n`;
+                        // Build a comprehensive prompt using 10/10 template with CodeDNA instructions
+                        const workerPrompt = buildWorkerPrompt({
+                            task: {
+                                id: dt.task.id,
+                                title: dt.task.title,
+                                description: dt.task.description,
+                                acceptance_criteria: parseJsonArray(dt.task.acceptance_criteria),
+                            },
+                            worker: dt.worker,
+                            epicContext: {
+                                title: epic.title,
+                                description: goal,
+                            },
+                        }, 'standard'); // Use standard tier for dispatched tasks
+                        // Escape the prompt for embedding in Task() call
+                        // Use a simplified version for the dispatch call that references the full context
+                        const dispatchPrompt = [
+                            `# Task: ${dt.task.title}`,
+                            `**Task ID:** ${dt.task.id}`,
+                            `**Epic:** ${epic.title}`,
+                            ``,
+                            dt.task.description || '',
+                            ``,
+                            `## CodeDNA Priority`,
+                            `If this task involves CRUD/API operations, use codedna_generate_api FIRST.`,
+                            `Look for Entity DSL in description (e.g., "User(email:string:unique)").`,
+                            ``,
+                            `## Protocol`,
+                            `1. Call task_start(task_id="${dt.task.id}")`,
+                            `2. Use memory_search and codebase_find before writing code`,
+                            `3. Implement requirements`,
+                            `4. Call task_complete(task_id="${dt.task.id}", summary="...")`,
+                        ].join('\n');
+                        output += `Task(subagent_type="general-purpose", prompt="${dispatchPrompt.replace(/"/g, '\\"').replace(/\n/g, '\\n')}")\n`;
                     }
                     output += `\`\`\`\n\n`;
                     output += `**Note:** All ${dispatchable.length} tasks are ready for parallel execution. `;

package/dist/helpers/workers.d.ts

@@ -1,3 +1,4 @@
+import { type WorkerPromptParams, type TaskContext, type EpicContext, type AttachedContext, type SiblingTask } from '../templates/worker-prompt.js';
 export interface ExpertWorker {
     id: string;
     name: string;
@@ -6,9 +7,19 @@ export interface ExpertWorker {
     capabilities: string[];
     promptTemplate: string;
 }
+export type { WorkerPromptParams, TaskContext, EpicContext, AttachedContext, SiblingTask };
 export declare const EXPERT_WORKERS: Record<string, ExpertWorker>;
 /**
- * Build a structured worker prompt that includes task context, protocol, error handling
+ * Build a structured worker prompt using the 10/10 AI System Prompt Architecture
+ *
+ * This function uses the new template system that includes:
+ * - XML semantic boundaries for machine-parseable structure
+ * - CodeDNA integration instructions (95-99% token savings for CRUD)
+ * - Tool usage priorities (memory_search, codebase_find before writing)
+ * - Tier-based complexity (minimal/standard/professional)
+ *
+ * @param params - Task, worker, and context information
+ * @param tier - Prompt complexity tier (default: 'standard')
  */
 export declare function buildWorkerPrompt(params: {
     task: {
@@ -31,6 +42,32 @@ export declare function buildWorkerPrompt(params: {
         title: string;
         status: string;
     }>;
+}, tier?: 'minimal' | 'standard' | 'professional'): string;
+/**
+ * Legacy buildWorkerPrompt for backwards compatibility
+ * @deprecated Use buildWorkerPrompt with tier parameter instead
+ */
+export declare function buildWorkerPromptLegacy(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

@@ -1,6 +1,11 @@
 // =============================================================================
 // Expert Worker Definitions (Orchestration System)
 // =============================================================================
+//
+// Updated with 10/10 AI System Prompt Architecture and CodeDNA integration.
+// Workers now know to use CodeDNA generators before writing boilerplate code.
+//
+import { buildWorkerPromptWithCodeDNA, } from '../templates/worker-prompt.js';
 export const EXPERT_WORKERS = {
     'schema-expert': {
         id: 'schema-expert',
@@ -14,7 +19,10 @@ export const EXPERT_WORKERS = {
 - Index optimisation
 - Data modelling decisions
 
-Focus only on schema-related changes. Do not modify application code outside your domain.
+CODEDNA: If task includes Entity DSL (e.g., "User(email:string:unique)"),
+the API layer will be generated automatically. Focus only on SQL schema.
+
+Focus only on schema-related changes. Do not modify application code.
 When complete, provide a concise summary of changes made.`,
     },
     'api-expert': {
@@ -28,7 +36,12 @@ When complete, provide a concise summary of changes made.`,
 - Request validation and parsing
 - Response formatting
 - Error handling for endpoints
-- API documentation
+
+CODEDNA PRIORITY: Before writing CRUD code manually, check if CodeDNA can generate it:
+- Look for Entity DSL in task (e.g., "User(email:string:unique, password:string:hashed)")
+- Call codedna_generate_api(spec, framework="express", options={...})
+- This generates models, controllers, routes, validation in seconds
+- Only write manually for complex business logic that can't be generated
 
 Focus only on API-related changes. Do not modify schema or extraction code.
 When complete, provide a concise summary of endpoints created or modified.`,
@@ -45,6 +58,9 @@ When complete, provide a concise summary of endpoints created or modified.`,
 - MCP resources and prompts
 - Server configuration
 
+TOOLS: Use memory_search to find existing MCP patterns before implementing.
+TOOLS: Use codebase_find to locate similar tool definitions.
+
 Focus only on MCP-related changes. Follow MCP SDK patterns exactly.
 When complete, provide a concise summary of tools added or modified.`,
     },
@@ -60,6 +76,9 @@ When complete, provide a concise summary of tools added or modified.`,
 - Fact and relationship extraction
 - Multi-language support
 
+TOOLS: Use codebase_context to understand file dependencies before changes.
+TOOLS: Use memory_search for existing extraction patterns.
+
 Focus only on extraction logic. Follow the BaseExtractor pattern.
 When complete, provide a concise summary of extraction capabilities added.`,
     },
@@ -75,6 +94,9 @@ When complete, provide a concise summary of extraction capabilities added.`,
 - Import/export wiring
 - Dependency management
 
+TOOLS: Use codebase_map to understand project structure before changes.
+TOOLS: Use codebase_context to see file dependencies.
+
 Focus on integration without modifying core implementation logic.
 When complete, provide a concise summary of integrations configured.`,
     },
@@ -84,7 +106,12 @@ When complete, provide a concise summary of integrations configured.`,
         description: 'Handles tasks that do not fit other expert domains',
         domains: ['**/*'],
         capabilities: ['general-development', 'refactoring', 'documentation', 'testing'],
-        promptTemplate: `You are a general purpose development expert. Handle this task with care:
+        promptTemplate: `You are a general purpose development expert.
+
+CODEDNA: For CRUD/API tasks, use codedna_generate_api before writing code manually.
+TOOLS: Use memory_search and codebase_find before implementing from scratch.
+
+Handle this task with care:
 - Follow existing code patterns
 - Make minimal necessary changes
 - Document your reasoning
@@ -93,9 +120,49 @@ When complete, provide a concise summary of work done.`,
     },
 };
 /**
- * Build a structured worker prompt that includes task context, protocol, error handling
+ * Build a structured worker prompt using the 10/10 AI System Prompt Architecture
+ *
+ * This function uses the new template system that includes:
+ * - XML semantic boundaries for machine-parseable structure
+ * - CodeDNA integration instructions (95-99% token savings for CRUD)
+ * - Tool usage priorities (memory_search, codebase_find before writing)
+ * - Tier-based complexity (minimal/standard/professional)
+ *
+ * @param params - Task, worker, and context information
+ * @param tier - Prompt complexity tier (default: 'standard')
+ */
+export function buildWorkerPrompt(params, tier = 'standard') {
+    const { task, worker, epicContext, attachedContext, siblingTasks } = params;
+    // Normalize acceptance_criteria to array
+    const criteria = Array.isArray(task.acceptance_criteria)
+        ? task.acceptance_criteria
+        : (task.acceptance_criteria ? [task.acceptance_criteria] : []);
+    // Normalize attached context to proper type
+    const normalizedContext = (attachedContext || []).map(ctx => ({
+        type: ctx.type,
+        content: ctx.content,
+        source: ctx.source,
+    }));
+    // Use the new 10/10 template system
+    return buildWorkerPromptWithCodeDNA({
+        task: {
+            id: task.id,
+            title: task.title,
+            description: task.description,
+            acceptance_criteria: criteria,
+        },
+        worker,
+        epicContext,
+        attachedContext: normalizedContext,
+        siblingTasks,
+        tier,
+    });
+}
+/**
+ * Legacy buildWorkerPrompt for backwards compatibility
+ * @deprecated Use buildWorkerPrompt with tier parameter instead
  */
-export function buildWorkerPrompt(params) {
+export function buildWorkerPromptLegacy(params) {
     const { task, worker, epicContext, attachedContext, siblingTasks } = params;
     let prompt = '';
     // Worker domain introduction

package/dist/templates/orchestrator-prompt.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Build orchestrator system prompt
+ *
+ * Orchestrators:
+ * - Break down complex work into tasks
+ * - Delegate implementation to specialist workers
+ * - Coordinate parallel execution
+ * - Track progress and handle failures
+ *
+ * Orchestrators do NOT:
+ * - Write implementation code
+ * - Provide detailed technical solutions in task descriptions
+ * - Duplicate work that workers should do
+ */
+export declare function buildOrchestratorPrompt(params: {
+    epicTitle?: string;
+    epicGoal?: string;
+    availableWorkers?: string[];
+}): string;
+/**
+ * Get CodeDNA usage hint for task descriptions
+ */
+export declare function getCodeDNAHint(entitySpec: string): string;
+/**
+ * Validate task description doesn't contain code
+ */
+export declare function validateTaskDescription(description: string): {
+    valid: boolean;
+    warnings: string[];
+};