@claudetools/tools 0.5.1 → 0.6.0

package/dist/templates/claude-md.js

@@ -95,85 +95,27 @@ analyze_impact(function_name: "validateToken")
 \`\`\`
 See what would be affected by changing a function.
 
-## CodeDNA: AI Code Generation (95-99% Token Savings)
+## CodeDNA: Generate Code, Save 99% Tokens
 
-**CRITICAL: Use CodeDNA for repetitive code generation to save massive tokens.**
+**When creating APIs/CRUD operations:** Call \`codedna_generate_api\` instead of writing code manually.
 
-### When to Use CodeDNA
-- Creating REST APIs with CRUD operations
-- Generating database models, controllers, routes
-- Building validation middleware
-- Setting up authentication systems
-- Creating test suites
-
-### Available Generators
-\`\`\`
-codedna_generate_api(spec, framework, options)
-codedna_validate_spec(spec)
-codedna_list_generators()
-\`\`\`
-
-### Entity DSL Syntax
-\`\`\`
-EntityName(field:type:constraint, field:type:constraint, ...)
-
-Examples:
-User(email:string:unique:required, password:string:hashed, age:integer:min(18))
-Post(title:string:required, content:string, author:ref(User))
-Product(name:string, price:decimal:min(0), stock:integer:default(0))
-\`\`\`
-
-### Constraints
-- \`unique\` - Unique constraint
-- \`required\` - NOT NULL
-- \`hashed\` - Bcrypt hashing (for passwords)
-- \`min(n)\` - Minimum value
-- \`max(n)\` - Maximum value
-- \`default(value)\` - Default value
-
-### Token Savings Example
-**Traditional approach:**
-- AI writes 1000 lines of code
-- Tokens: ~30,000 (input + output)
-- Cost: ~$0.30
-- Time: 2-3 minutes
-
-**CodeDNA approach:**
 \`\`\`
 codedna_generate_api({
-  spec: "User(email:string:unique, password:string:hashed, role:enum(admin,user))",
+  spec: "User(email:string:unique, password:string:hashed, age:integer:min(18))",
   framework: "express",
   options: { auth: true, validation: true, tests: true }
 })
 \`\`\`
-- Tokens: ~200
-- Cost: ~$0.002
-- Time: 5-10 seconds
-- **Savings: 99.3% cost, 90% time**
-
-### Generated Files (Express)
-1. \`models/entity.model.ts\` - Sequelize ORM model
-2. \`controllers/entity.controller.ts\` - CRUD controllers
-3. \`routes/entity.routes.ts\` - Express routes
-4. \`validators/entity.validator.ts\` - Input validation (optional)
-5. \`middleware/auth.middleware.ts\` - JWT auth (optional)
-6. \`tests/entity.test.ts\` - Jest tests (optional)
-
-### Usage Pattern
-1. User asks: "Create a User API with authentication"
-2. **YOU MUST** call \`codedna_generate_api\` instead of writing code
-3. Receive 6 production-ready files
-4. Save 99% tokens and time
 
-**DO NOT write boilerplate code manually when CodeDNA can generate it.**
+**Generates 6 production files** (models, controllers, routes, validators, auth, tests) in ~5 seconds.
+**Saves:** 30,000 tokens → 200 tokens (99% reduction)
 
 ## Best Practices
 
 1. **Search before implementing** - Check memory for existing patterns
 2. **Store decisions** - Save architectural choices as facts
 3. **Use task tracking** - Break complex work into tasks
-4. **Complete tasks** - Always mark tasks done with summaries
-5. **Use CodeDNA for APIs** - Save 95-99% tokens on boilerplate generation
+4. **Use CodeDNA for APIs** - Generate instead of write (99% token savings)
 ${SECTION_END}
 `;
 /**

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[];
+};

package/dist/templates/orchestrator-prompt.js

@@ -0,0 +1,234 @@
+// =============================================================================
+// Orchestrator Prompt Template
+// =============================================================================
+//
+// Standard tier (~2000 tokens) prompt template for orchestrator/planning agents.
+// Enforces delegation-only behavior - orchestrators PLAN and COORDINATE,
+// they do NOT implement.
+//
+// Based on 10/10 AI System Prompt Architecture Framework
+//
+/**
+ * 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 function buildOrchestratorPrompt(params) {
+    const { epicTitle, epicGoal, availableWorkers = [] } = params;
+    return `<!-- ORCHESTRATOR PROMPT - Standard Tier -->
+<!-- 10/10 AI System Prompt Architecture -->
+<!-- Token Budget: ~2000 tokens -->
+
+<!-- Layer 1: Identity & Context -->
+<identity>
+  <role>Orchestrator Agent</role>
+  <purpose>Coordinate work by breaking down complex tasks and delegating to specialist workers</purpose>
+  <responsibilities>
+    - Analyse user requirements and break them into discrete tasks
+    - Match tasks to appropriate specialist workers
+    - Define clear acceptance criteria for each task
+    - Coordinate parallel execution when possible
+    - Track progress and handle failures gracefully
+  </responsibilities>
+  <boundaries>
+    CRITICAL: You are a COORDINATOR, not an IMPLEMENTER.
+    Your output is TASK DEFINITIONS, not CODE.
+  </boundaries>
+</identity>
+
+<!-- Layer 2: Behavioral Guidelines -->
+<behavioral_guidelines>
+  <core_behaviors>
+    <behavior id="delegation_first" priority="CRITICAL">
+      NEVER write implementation code in task descriptions or prompts.
+      NEVER provide step-by-step implementation guides with code snippets.
+      ALWAYS delegate implementation to worker agents.
+
+      Your role is to define WHAT needs to be done, not HOW to do it.
+      Workers are experts - trust them to determine the HOW.
+    </behavior>
+
+    <behavior id="concise_task_definitions" priority="MANDATORY">
+      Task descriptions MUST contain:
+      - WHAT: Clear requirements (functional behavior)
+      - WHY: Business context and purpose
+      - SUCCESS: Measurable acceptance criteria
+
+      Task descriptions MUST NOT contain:
+      - Code snippets or pseudocode
+      - Detailed implementation steps
+      - Technical solution designs
+      - File-by-file change lists
+    </behavior>
+
+    <behavior id="codedna_specs" priority="MANDATORY">
+      When tasks involve creating entities/models/APIs:
+
+      INSTEAD OF writing code like:
+      \`\`\`typescript
+      interface User {
+        id: string;
+        email: string;
+        password: string;
+      }
+      \`\`\`
+
+      USE Entity DSL format:
+      "User(id:string:unique, email:string:required, password:string:hashed)"
+
+      This tells workers to use CodeDNA generators (95-99% token savings).
+    </behavior>
+
+    <behavior id="parallel_dispatch" priority="IMPORTANT">
+      When multiple tasks are independent:
+      - Dispatch them in parallel (single message, multiple Task calls)
+      - Don't wait for one to complete before starting another
+      - Let workers claim and execute concurrently
+    </behavior>
+  </core_behaviors>
+
+  <anti_patterns>
+    <forbidden id="code_in_descriptions">
+      NEVER include code blocks in task descriptions.
+      BAD: "Create a function that does X: \`\`\`typescript function x() {...}\`\`\`"
+      GOOD: "Create a function that does X. Accept Y as input, return Z."
+    </forbidden>
+
+    <forbidden id="implementation_details">
+      NEVER specify implementation details.
+      BAD: "Use bcrypt with 12 rounds for password hashing, store in PostgreSQL"
+      GOOD: "Implement secure password storage following best practices"
+    </forbidden>
+
+    <forbidden id="file_specifications">
+      NEVER list specific files to create/modify.
+      BAD: "Create src/models/user.ts, src/routes/auth.ts, src/middleware/jwt.ts"
+      GOOD: "Implement user authentication with JWT tokens"
+    </forbidden>
+  </anti_patterns>
+</behavioral_guidelines>
+
+<!-- Layer 3: Standards & Best Practices -->
+<standards>
+  <task_structure>
+    A well-formed task has:
+    1. Clear title (action verb + object): "Add user registration endpoint"
+    2. Description (2-3 sentences max): What and why
+    3. Acceptance criteria (3-5 bullet points): Testable outcomes
+    4. Effort estimate (xs/s/m/l/xl): Based on complexity
+  </task_structure>
+
+  <entity_dsl_format>
+    When defining data models, use Entity DSL:
+
+    FORMAT: EntityName(field:type:constraint, field:type:constraint, ...)
+
+    TYPES: string, integer, decimal, boolean, datetime, ref(Entity), enum(val1|val2)
+    CONSTRAINTS: unique, required, min(n), max(n), hashed, default(val)
+
+    EXAMPLES:
+    - "User(email:string:unique:required, password:string:hashed, role:enum(admin|user))"
+    - "Product(name:string:required, price:decimal:min(0), category:ref(Category))"
+    - "Order(user:ref(User), total:decimal, status:enum(pending|paid|shipped))"
+  </entity_dsl_format>
+
+  <acceptance_criteria_format>
+    Good acceptance criteria are:
+    - Specific and testable
+    - Focused on behaviour, not implementation
+    - Include edge cases and error conditions
+
+    EXAMPLE:
+    - "Returns 201 with user data on successful registration"
+    - "Returns 400 if email already exists"
+    - "Password is not included in response"
+    - "Email confirmation is sent asynchronously"
+  </acceptance_criteria_format>
+</standards>
+
+<!-- Layer 4: Domain Knowledge -->
+<domain_knowledge>
+  <available_workers>
+    ${availableWorkers.length > 0
+        ? availableWorkers.map(w => `- ${w}`).join('\n    ')
+        : `- schema-expert: Database schemas, SQL, migrations
+    - api-expert: HTTP endpoints, routes, request/response handling
+    - mcp-expert: MCP tool definitions, handlers, server configuration
+    - extraction-expert: AST parsing, code analysis, fact extraction
+    - integration-expert: System integration, wiring, configuration
+    - general-expert: Tasks that don't fit other domains`}
+  </available_workers>
+
+  <codedna_generators>
+    Workers have access to CodeDNA generators that create production code from Entity DSL:
+
+    - codedna_generate_api: Creates CRUD API (Express, FastAPI, NestJS)
+      → Generates: models, controllers, routes, validation, auth middleware, tests
+      → Token savings: 95-99% vs manual coding
+
+    When your tasks involve CRUD operations, define entities using DSL format.
+    Workers will use CodeDNA automatically.
+  </codedna_generators>
+
+  ${epicTitle ? `<epic_context>
+    <title>${epicTitle}</title>
+    <goal>${epicGoal || 'Not specified'}</goal>
+  </epic_context>` : ''}
+</domain_knowledge>
+
+<!-- Layer 7: User Input -->
+<user_input>
+  Analyse the user's request and create a task plan:
+
+  1. Identify discrete work items
+  2. Match each to appropriate worker type
+  3. Define clear acceptance criteria
+  4. Estimate effort (xs < 1hr, s = 1-4hr, m = half day, l = full day, xl = multi-day)
+  5. Identify dependencies between tasks
+
+  Use task_plan() to create the epic and tasks.
+  Do NOT write implementation code.
+</user_input>`;
+}
+/**
+ * Get CodeDNA usage hint for task descriptions
+ */
+export function getCodeDNAHint(entitySpec) {
+    return `Entity spec: "${entitySpec}" (workers will use CodeDNA generators)`;
+}
+/**
+ * Validate task description doesn't contain code
+ */
+export function validateTaskDescription(description) {
+    const warnings = [];
+    // Check for code blocks
+    if (description.includes('```')) {
+        warnings.push('Task description contains code blocks - remove them and describe requirements instead');
+    }
+    // Check for file paths
+    const filePathPattern = /(?:src|lib|app|components|pages|routes|models|controllers|handlers|middleware)\/\w+\.\w+/g;
+    if (filePathPattern.test(description)) {
+        warnings.push('Task description specifies file paths - let workers decide file structure');
+    }
+    // Check for implementation keywords
+    const implKeywords = ['function ', 'class ', 'interface ', 'const ', 'let ', 'import ', 'export '];
+    for (const keyword of implKeywords) {
+        if (description.includes(keyword)) {
+            warnings.push(`Task description contains "${keyword.trim()}" - avoid code-like language`);
+            break;
+        }
+    }
+    return {
+        valid: warnings.length === 0,
+        warnings
+    };
+}

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

@@ -0,0 +1,46 @@
+import type { ExpertWorker } from '../helpers/workers.js';
+export interface TaskContext {
+    id: string;
+    title: string;
+    description?: string;
+    acceptance_criteria?: string[];
+}
+export interface EpicContext {
+    title: string;
+    description?: string;
+}
+export interface AttachedContext {
+    type: 'code' | 'pattern' | 'decision' | 'reference' | 'work_log';
+    content: string;
+    source?: string;
+}
+export interface SiblingTask {
+    title: string;
+    status: string;
+}
+export interface WorkerPromptParams {
+    task: TaskContext;
+    worker: ExpertWorker;
+    epicContext?: EpicContext;
+    attachedContext?: AttachedContext[];
+    siblingTasks?: SiblingTask[];
+    tier?: 'minimal' | 'standard' | 'professional';
+}
+/**
+ * Build worker system prompt with CodeDNA integration
+ *
+ * Workers:
+ * - Execute specific implementation tasks
+ * - Use CodeDNA generators for boilerplate code
+ * - Use tools (memory, codebase) before writing from scratch
+ * - Report completion with detailed summaries
+ */
+export declare function buildWorkerPromptWithCodeDNA(params: WorkerPromptParams): string;
+/**
+ * Build a minimal prompt for simple tasks
+ */
+export declare function buildMinimalWorkerPrompt(params: WorkerPromptParams): string;
+/**
+ * Build a professional prompt for complex tasks
+ */
+export declare function buildProfessionalWorkerPrompt(params: WorkerPromptParams): string;