@claudetools/tools 0.7.2 → 0.7.4

package/dist/helpers/config.d.ts

@@ -34,7 +34,8 @@ export declare function resolveProjectId(): string;
 export declare function resolveProjectIdAsync(): Promise<string>;
 /**
  * Gets the default project ID (synchronous version)
- * Checks session-context.md first, then config, then falls back to cwd resolution
+ * ALWAYS checks session-context.md first (even if cached), then config, then falls back to cwd resolution
+ * This handles race conditions where MCP server starts before session-start hook writes the file
  */
 export declare function getDefaultProjectId(): string;
 /**

package/dist/helpers/config.js

@@ -100,11 +100,21 @@ export function resolveProjectId() {
  * Should be called during server startup
  */
 export async function resolveProjectIdAsync() {
-    // Return cached result if available
+    // ALWAYS check session-context.md first (even if cached) - handles race condition
+    // where MCP server starts before Claude Code's session-start hook writes the file
+    const sessionProjectId = getProjectIdFromSessionContext();
+    if (sessionProjectId) {
+        if (resolvedProjectId !== sessionProjectId) {
+            mcpLogger.info('MEMORY', `Project resolved from session context: ${sessionProjectId} (was: ${resolvedProjectId})`);
+            resolvedProjectId = sessionProjectId;
+        }
+        return resolvedProjectId;
+    }
+    // Return cached result if available (and no session-context.md)
     if (resolvedProjectId) {
         return resolvedProjectId;
     }
-    // Check environment variable first
+    // Check environment variable
     if (process.env.CLAUDETOOLS_PROJECT_ID) {
         const envProjectId = process.env.CLAUDETOOLS_PROJECT_ID;
         // Validate UUID format
@@ -116,14 +126,6 @@ export async function resolveProjectIdAsync() {
         mcpLogger.debug('MEMORY', `Using project ID from env: ${resolvedProjectId}`);
         return resolvedProjectId;
     }
-    // Check session-context.md (written by Claude Code's session-start hook)
-    // This is the most reliable source since MCP server's cwd isn't the project dir
-    const sessionProjectId = getProjectIdFromSessionContext();
-    if (sessionProjectId) {
-        resolvedProjectId = sessionProjectId;
-        mcpLogger.info('MEMORY', `Project resolved from session context: ${resolvedProjectId}`);
-        return resolvedProjectId;
-    }
     const cwd = process.cwd();
     // Check projects.json cache
     const binding = findProjectBinding(cwd);
@@ -165,16 +167,23 @@ export async function resolveProjectIdAsync() {
 let _defaultProjectId = null;
 /**
  * Gets the default project ID (synchronous version)
- * Checks session-context.md first, then config, then falls back to cwd resolution
+ * ALWAYS checks session-context.md first (even if cached), then config, then falls back to cwd resolution
+ * This handles race conditions where MCP server starts before session-start hook writes the file
  */
 export function getDefaultProjectId() {
-    if (_defaultProjectId) {
-        return _defaultProjectId;
-    }
-    // Check session-context.md first (most reliable for MCP server)
+    // ALWAYS check session-context.md first - it may have been written after we cached a fallback value
+    // This handles the race condition where MCP server starts before Claude Code's session-start hook runs
     const sessionProjectId = getProjectIdFromSessionContext();
     if (sessionProjectId) {
-        _defaultProjectId = sessionProjectId;
+        // Update cache if different (session-context.md is authoritative)
+        if (_defaultProjectId !== sessionProjectId) {
+            mcpLogger.debug('MEMORY', `Updating project ID from session-context: ${sessionProjectId} (was: ${_defaultProjectId})`);
+            _defaultProjectId = sessionProjectId;
+        }
+        return _defaultProjectId;
+    }
+    // If we have a cached value and no session-context.md, use cache
+    if (_defaultProjectId) {
         return _defaultProjectId;
     }
     // Try config second
@@ -198,10 +207,19 @@ export function getDefaultProjectId() {
  * Async version for server startup
  */
 export async function getDefaultProjectIdAsync() {
+    // ALWAYS check session-context.md first - same as sync version
+    const sessionProjectId = getProjectIdFromSessionContext();
+    if (sessionProjectId) {
+        if (_defaultProjectId !== sessionProjectId) {
+            mcpLogger.debug('MEMORY', `Updating project ID from session-context (async): ${sessionProjectId} (was: ${_defaultProjectId})`);
+            _defaultProjectId = sessionProjectId;
+        }
+        return _defaultProjectId;
+    }
     if (_defaultProjectId) {
         return _defaultProjectId;
     }
-    // Try config first
+    // Try config
     if (config.defaultProjectId) {
         if (!isValidProjectId(config.defaultProjectId)) {
             // Legacy format - convert to local_ format instead of throwing

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 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## CodeDNA: Generate Code, Save 99% Tokens\n\n**When creating APIs/CRUD operations:** Call `codedna_generate_api` instead of writing code manually.\n\n```\ncodedna_generate_api({\n  spec: \"User(email:string:unique, password:string:hashed, age:integer:min(18))\",\n  framework: \"express\",\n  options: { auth: true, validation: true, tests: true }\n})\n```\n\n**Generates 6 production files** (models, controllers, routes, validators, auth, tests) in ~5 seconds.\n**Saves:** 30,000 tokens \u2192 200 tokens (99% reduction)\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. **Use CodeDNA for APIs** - Generate instead of write (99% token savings)\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### Start with codebase_map() - ALWAYS\n```\ncodebase_map()  # FIRST TOOL when exploring unfamiliar code\n```\n**When to use:** Starting a new task, exploring unfamiliar code, understanding project structure, finding entry points.\n\nThe map shows:\n- Project structure and key directories\n- Entry points and their exports\n- Framework detection (React, Express, etc.)\n- Key symbols and their locations\n\n**Use codebase_map BEFORE using Grep/Glob** - it gives you the lay of the land so you know where to look.\n\n### Then use targeted tools\n```\ncodebase_find(\"UserService\")  # Find specific symbols/files\ncodebase_context(\"src/auth.ts\")  # Get file dependencies\nanalyze_impact(\"validateToken\")  # See what changing a function affects\n```\n\n## CodeDNA: Generate Code, Save 99% Tokens\n\n**When creating APIs/CRUD operations:** Call `codedna_generate_api` instead of writing code manually.\n\n```\ncodedna_generate_api({\n  spec: \"User(email:string:unique, password:string:hashed, age:integer:min(18))\",\n  framework: \"express\",\n  options: { auth: true, validation: true, tests: true }\n})\n```\n\n**Generates 6 production files** (models, controllers, routes, validators, auth, tests) in ~5 seconds.\n**Saves:** 30,000 tokens \u2192 200 tokens (99% reduction)\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. **Use CodeDNA for APIs** - Generate instead of write (99% token savings)\n<!-- CLAUDETOOLS:END -->\n";
 /**
  * Project-level CLAUDE.md content - added to .claude/CLAUDE.md
  */

package/dist/templates/claude-md.js

@@ -82,18 +82,26 @@ Mark tasks done with a summary of work completed. **Always call this when a task
 
 ## Codebase Intelligence
 
-### Finding Code
+### Start with codebase_map() - ALWAYS
 \`\`\`
-codebase_map()           # Get overview of project structure
-codebase_find("UserService")  # Find symbols/files
-codebase_context("src/auth.ts")  # Get file dependencies
+codebase_map()  # FIRST TOOL when exploring unfamiliar code
 \`\`\`
+**When to use:** Starting a new task, exploring unfamiliar code, understanding project structure, finding entry points.
+
+The map shows:
+- Project structure and key directories
+- Entry points and their exports
+- Framework detection (React, Express, etc.)
+- Key symbols and their locations
 
-### Impact Analysis
+**Use codebase_map BEFORE using Grep/Glob** - it gives you the lay of the land so you know where to look.
+
+### Then use targeted tools
 \`\`\`
-analyze_impact(function_name: "validateToken")
+codebase_find("UserService")  # Find specific symbols/files
+codebase_context("src/auth.ts")  # Get file dependencies
+analyze_impact("validateToken")  # See what changing a function affects
 \`\`\`
-See what would be affected by changing a function.
 
 ## CodeDNA: Generate Code, Save 99% Tokens
 

package/dist/templates/orchestrator-prompt.js

@@ -48,6 +48,21 @@ export function buildOrchestratorPrompt(params) {
 <!-- Layer 2: Behavioral Guidelines -->
 <behavioral_guidelines>
   <core_behaviors>
+    <behavior id="understand_first" priority="CRITICAL">
+      BEFORE creating a task plan, understand the codebase:
+
+      1. Call codebase_map() FIRST
+         → See project structure, entry points, frameworks
+         → Identify which areas of the codebase are relevant
+         → Understand existing patterns before planning changes
+
+      2. Call memory_search() for past decisions
+         → Check for architectural constraints
+         → Find relevant patterns already established
+
+      This ensures your plan fits the existing codebase architecture.
+    </behavior>
+
     <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.

package/dist/templates/worker-prompt.js

@@ -92,18 +92,24 @@ function buildBehavioralSection(taskId) {
     <behavior id="tool_first" priority="MANDATORY">
       BEFORE writing code, use available tools:
 
-      1. memory_search: Check for existing patterns and decisions
+      1. codebase_map: START HERE - Get project overview
+         → Understand project structure and key entry points
+         → Identify frameworks and patterns in use
+         → Find relevant directories before diving in
+         → Use BEFORE Grep/Glob for unfamiliar code
+
+      2. memory_search: Check for existing patterns and decisions
          → "How was authentication implemented?"
          → "What patterns are used for X?"
 
-      2. codebase_find: Find similar implementations
+      3. codebase_find: Find specific symbols/files
          → Search for existing code to extend/adapt
 
-      3. docs_get: Retrieve cached documentation
-         → Get up-to-date API references
-
       4. codebase_context: Understand file dependencies
          → See what a file imports/exports
+
+      5. docs_get: Retrieve cached documentation
+         → Get up-to-date API references
     </behavior>
 
     <behavior id="minimal_changes" priority="IMPORTANT">

package/package.json

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