@claudetools/tools 0.6.0 → 0.7.1

package/dist/templates/orchestrator-prompt.js

@@ -127,6 +127,25 @@ export function buildOrchestratorPrompt(params) {
     4. Effort estimate (xs/s/m/l/xl): Based on complexity
   </task_structure>
 
+  <documentation_standards priority="MANDATORY">
+    When creating plans, research, or documentation:
+
+    DIRECTORY STRUCTURE:
+    - docs/           → Project documentation
+    - docs/research/  → Research and analysis
+    - docs/decisions/ → Architecture Decision Records
+
+    NAMING CONVENTIONS:
+    - lowercase-with-hyphens.md (NEVER underscores or spaces)
+    - Date prefix for temporal docs: YYYY-MM-DD-topic.md
+    - Example: docs/research/2025-12-05-auth-comparison.md
+
+    ANTI-PATTERNS (NEVER DO):
+    - PLAN.md, NOTES.md, TODO.md in project root
+    - SCREAMING_CASE_FILENAMES.md
+    - Random .md files scattered in src/ or root
+  </documentation_standards>
+
   <entity_dsl_format>
     When defining data models, use Entity DSL:
 
@@ -168,15 +187,23 @@ export function buildOrchestratorPrompt(params) {
     - 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_generators priority="CRITICAL">
+    CodeDNA generates production code from Entity DSL - workers MUST check availability first.
+
+    BEFORE creating any task involving APIs, CRUD, or UI components:
+    1. Workers should call codedna_list_generators() to see available generators
+    2. If a generator exists, use it instead of writing code manually
+
+    AVAILABLE DOMAINS:
+    - api: Express, FastAPI, NestJS (full CRUD with auth, validation, tests)
+    - frontend: React/Next.js, Vue 3 (pages, forms, tables)
+    - component: Forms, tables, cards, modals (React, Vue, Svelte)
 
-    - codedna_generate_api: Creates CRUD API (Express, FastAPI, NestJS)
-      → Generates: models, controllers, routes, validation, auth middleware, tests
-      → Token savings: 95-99% vs manual coding
+    INCLUDE IN TASK DESCRIPTIONS:
+    When tasks involve entities, include the DSL spec so workers know to use CodeDNA:
+    "Create user registration. Entity: User(email:string:unique, password:string:hashed)"
 
-    When your tasks involve CRUD operations, define entities using DSL format.
-    Workers will use CodeDNA automatically.
+    Token savings: 95-99% vs manual coding
   </codedna_generators>
 
   ${epicTitle ? `<epic_context>

package/dist/templates/worker-prompt.js

@@ -71,16 +71,18 @@ function buildBehavioralSection(taskId) {
     <behavior id="codedna_first" priority="MANDATORY">
       BEFORE writing code manually, check if CodeDNA can generate it:
 
-      FOR CRUD/API operations:
-      → Use codedna_generate_api(spec, framework, options)
+      DISCOVERY WORKFLOW:
+      1. Call codedna_list_generators() to see available generators
+      2. Check if task includes Entity DSL format
+         Example: "User(email:string:unique, password:string:hashed)"
+      3. Detect framework from project (package.json, existing code)
+      4. Match detected framework to generator capabilities
+      5. Call appropriate generator with detected settings
+
+      BENEFITS:
       → Saves 95-99% tokens vs manual coding
       → Generates production-ready code with validation, auth, tests
 
-      FOR Entity definitions:
-      → Check if task includes Entity DSL format
-      → Example: "User(email:string:unique, password:string:hashed)"
-      → Call codedna_generate_api with the spec
-
       ONLY write code manually when:
       - Logic is too complex for generation
       - Modifying existing code (not creating new)
@@ -131,6 +133,38 @@ function buildStandardsSection() {
     - Include file paths with line numbers in references
   </formatting>
 
+  <documentation_files priority="MANDATORY">
+    NEVER create .md files in random locations. Follow these rules:
+
+    DIRECTORY STRUCTURE:
+    - docs/           → Project documentation, guides, specs
+    - docs/research/  → Research notes, analysis, investigations
+    - docs/decisions/ → Architecture Decision Records (ADRs)
+    - CHANGELOG.md    → Only in project root
+    - README.md       → Only in project root or package roots
+
+    NAMING CONVENTIONS:
+    - Use lowercase with hyphens: user-authentication-guide.md
+    - NEVER use spaces or underscores in filenames
+    - Include date prefix for time-sensitive docs: YYYY-MM-DD-topic.md
+      Example: 2025-12-05-api-migration-plan.md
+    - Research docs: YYYY-MM-DD-research-topic.md
+    - Decision records: NNNN-decision-title.md (e.g., 0001-use-jwt-auth.md)
+
+    ANTI-PATTERNS (NEVER DO):
+    - Creating PLAN.md, NOTES.md, TODO.md in project root
+    - Random capitalised filenames like IMPLEMENTATION_GUIDE.md
+    - Nested docs in src/ or lib/ directories
+    - Multiple README files outside package roots
+    - Temporary docs without dates (impossible to clean up later)
+
+    BEFORE CREATING ANY .md FILE:
+    1. Check if docs/ directory exists - create if needed
+    2. Determine correct subdirectory (research/, decisions/, etc.)
+    3. Use proper naming convention with date if temporal
+    4. Ask user if uncertain about placement
+  </documentation_files>
+
   <completion_summary>
     When calling task_complete, include:
     - Implementation: What you built/changed
@@ -145,16 +179,12 @@ function buildDomainSection(worker) {
     return `<!-- Layer 4: Domain Knowledge -->
 <domain_knowledge>
   <codedna_capabilities>
-    AVAILABLE GENERATORS:
-
-    1. codedna_generate_api(spec, framework, options)
-       - Frameworks: "express", "fastapi", "nestjs"
-       - Options: { auth: true, validation: true, tests: true }
-       - Generates: model, controller, routes, validation, auth, tests
-
-    2. codedna_validate_spec(spec)
-       - Validates Entity DSL syntax before generation
-       - Returns parsed structure or errors
+    CODEDNA DISCOVERY PATTERN:
+    1. Call codedna_list_generators() to see available generators
+    2. Each generator lists supported frameworks and options
+    3. Detect project framework from package.json/pyproject.toml
+    4. Match detected framework to generator capabilities
+    5. If no match, ASK the user which framework to use
 
     ENTITY DSL FORMAT:
     EntityName(field:type:constraint, field:type:constraint, ...)
@@ -165,20 +195,15 @@ function buildDomainSection(worker) {
     - enum(val1|val2|val3) - enumeration
 
     CONSTRAINTS:
-    - unique - unique constraint
-    - required - not null
-    - min(n), max(n) - numeric bounds
-    - hashed - for passwords (auto bcrypt)
-    - default(value) - default value
-
-    EXAMPLE:
-    codedna_generate_api({
-      spec: "User(email:string:unique:required, password:string:hashed, role:enum(admin|user|guest), created_at:datetime:default(now))",
-      framework: "express",
-      options: { auth: true, validation: true }
-    })
-    → Generates 6 production files in ~5 seconds
-    → Saves ~30,000 tokens vs manual implementation
+    - unique, required, min(n), max(n), hashed, default(value)
+    - UI hints: textarea, switch, radio (for form rendering)
+
+    WORKFLOW:
+    1. codedna_list_generators() → discover capabilities
+    2. codedna_validate_spec(spec) → validate DSL syntax
+    3. codedna_generate_*(spec, framework, options) → generate code
+
+    DO NOT assume frameworks exist - always discover via codedna_list_generators
   </codedna_capabilities>
 
   <worker_expertise>

package/dist/tools.js

@@ -952,6 +952,10 @@ export function registerToolDefinitions(server) {
                                 },
                             },
                         },
+                        package_json: {
+                            type: 'object',
+                            description: 'Optional: package.json content for pattern detection. If provided, generator will detect patterns (zod, yup, etc.) and use matching template variants.',
+                        },
                     },
                     required: ['spec', 'framework'],
                 },
@@ -993,6 +997,10 @@ export function registerToolDefinitions(server) {
                                 },
                             },
                         },
+                        package_json: {
+                            type: 'object',
+                            description: 'Optional: package.json content for pattern detection. Detects React Hook Form, Zod, TanStack Query, etc. and uses matching template variants.',
+                        },
                     },
                     required: ['spec', 'framework'],
                 },
@@ -1031,16 +1039,26 @@ export function registerToolDefinitions(server) {
                                 },
                             },
                         },
+                        package_json: {
+                            type: 'object',
+                            description: 'Optional: package.json content for pattern detection. Detects form libraries, validation tools, etc. and uses matching template variants.',
+                        },
                     },
                     required: ['spec', 'type', 'framework'],
                 },
             },
             {
                 name: 'codedna_list_generators',
-                description: 'List all available code generators and their capabilities.',
+                description: 'CALL THIS BEFORE writing any API, CRUD, or UI component code. Lists available code generators that save 95-99% tokens vs manual coding. Returns generators grouped by domain (api/frontend/component) with their capabilities. If a generator exists for your task, use codedna_generate_* instead of writing code manually.',
                 inputSchema: {
                     type: 'object',
-                    properties: {},
+                    properties: {
+                        domain: {
+                            type: 'string',
+                            enum: ['api', 'frontend', 'component'],
+                            description: 'Filter by domain: "api" for backend APIs, "frontend" for full frontend apps, "component" for individual UI components',
+                        },
+                    },
                 },
             },
             {
@@ -1057,6 +1075,87 @@ export function registerToolDefinitions(server) {
                     required: ['spec'],
                 },
             },
+            // =========================================================================
+            // CodeDNA Pattern Library Tools
+            // =========================================================================
+            {
+                name: 'codedna_list_patterns',
+                description: 'List coding patterns from the library. Returns best practices (compound components, TanStack Query, Zod) and anti-patterns to avoid (prop drilling, useEffect fetch). Use to understand what patterns are available for a project.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        category: {
+                            type: 'string',
+                            enum: ['components', 'hooks', 'forms', 'state', 'validation', 'styling', 'anti-patterns'],
+                            description: 'Filter by category',
+                        },
+                        recommended_only: {
+                            type: 'boolean',
+                            description: 'Only return recommended best-practice patterns',
+                        },
+                        include_anti_patterns: {
+                            type: 'boolean',
+                            description: 'Include anti-patterns in results (default: true)',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'codedna_get_pattern',
+                description: 'Get detailed documentation for a specific pattern including code examples, when to use/avoid, and migration guides. Use after codedna_list_patterns to get full details.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        pattern_id: {
+                            type: 'string',
+                            description: 'Pattern ID (e.g., "compound-components", "tanstack-query", "prop-drilling")',
+                        },
+                    },
+                    required: ['pattern_id'],
+                },
+            },
+            {
+                name: 'codedna_detect_patterns',
+                description: 'Detect which patterns are used in an existing codebase. Analyzes package.json dependencies and code samples to identify patterns and anti-patterns. Use before making changes to understand project conventions.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        package_json: {
+                            type: 'object',
+                            description: 'The project package.json object (with dependencies/devDependencies)',
+                        },
+                        code_samples: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Code snippets to analyze for pattern signals',
+                        },
+                    },
+                },
+            },
+            {
+                name: 'codedna_init_project',
+                description: 'Initialize a project with recommended patterns. For NEW projects, applies best-practice defaults. For EXISTING projects, use with auto_detect to match existing conventions.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        project_id: {
+                            type: 'string',
+                            description: 'Project ID from claudetools',
+                        },
+                        patterns: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Specific pattern IDs to apply (optional - uses recommended if not specified)',
+                        },
+                        project_type: {
+                            type: 'string',
+                            enum: ['new', 'existing'],
+                            description: '"new" for greenfield (uses recommended), "existing" for updating (detects patterns)',
+                        },
+                    },
+                    required: ['project_id'],
+                },
+            },
         ],
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudetools/tools",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Persistent AI memory, task management, and codebase intelligence for Claude Code",
   "type": "module",
   "main": "dist/index.js",