@e0ipso/ai-task-manager 1.26.3 → 1.26.4

package/templates/ai-task-manager/config/scripts/validate-plan-blueprint.cjs

@@ -2,245 +2,137 @@
 
 const fs = require('fs');
 const path = require('path');
-const { findTaskManagerRoot } = require('./shared-utils.cjs');
+const sharedUtils = require('./shared-utils.cjs');
+const {
+  findTaskManagerRoot,
+  findPlanById,
+  countTasks,
+  checkBlueprintExists,
+  getAllPlans,
+  validatePlanFile,
+  checkStandardRootShortcut,
+  resolvePlan
+} = sharedUtils;
 
 /**
  * Error logging utility
+ * @private
  * @param {string} message - Error message
  * @param {...any} args - Additional arguments to log
  */
-function errorLog(message, ...args) {
+function _errorLog(message, ...args) {
   console.error(`[ERROR] ${message}`, ...args);
 }
 
-/**
- * Find plan file and directory for a given plan ID
- * @param {string|number} planId - Plan ID to search for
- * @returns {Object|null} Object with planFile and planDir, or null if not found
- */
-function findPlanById(planId) {
-  const taskManagerRoot = findTaskManagerRoot();
-
-  if (!taskManagerRoot) {
-    errorLog('No .ai/task-manager directory found in current directory or any parent directory.');
-    return null;
-  }
-
-  // Convert planId to numeric for flexible matching (handles both "2" and "02")
-  const numericPlanId = parseInt(planId, 10);
-
-  if (isNaN(numericPlanId)) {
-    errorLog(`Invalid plan ID: ${planId}. Plan ID must be numeric.`);
-    return null;
-  }
-
-  const plansDir = path.join(taskManagerRoot, 'plans');
-  const archiveDir = path.join(taskManagerRoot, 'archive');
-
-  // Search both plans and archive directories
-  for (const dir of [plansDir, archiveDir]) {
-    if (!fs.existsSync(dir)) {
-      continue;
-    }
-
-    try {
-      const entries = fs.readdirSync(dir, { withFileTypes: true });
-
-      for (const entry of entries) {
-        // Match directory pattern: [plan-id]--* (with flexible ID matching)
-        if (entry.isDirectory()) {
-          // Extract numeric ID from directory name, stripping leading zeros
-          const dirMatch = entry.name.match(/^0*(\d+)--/);
-          if (dirMatch && parseInt(dirMatch[1], 10) === numericPlanId) {
-            const planDirPath = path.join(dir, entry.name);
-
-          try {
-            const planDirEntries = fs.readdirSync(planDirPath, { withFileTypes: true });
-
-            // Look for plan file: plan-[plan-id]--*.md (with flexible ID matching)
-            for (const planEntry of planDirEntries) {
-              if (planEntry.isFile()) {
-                // Extract numeric ID from filename, stripping leading zeros
-                const fileMatch = planEntry.name.match(/^plan-0*(\d+)--.*\.md$/);
-                if (fileMatch && parseInt(fileMatch[1], 10) === numericPlanId) {
-                  const planFilePath = path.join(planDirPath, planEntry.name);
-
-                  return {
-                    planFile: planFilePath,
-                    planDir: planDirPath
-                  };
-                }
-              }
-            }
-          } catch (err) {
-            errorLog(`Failed to read plan directory ${planDirPath}: ${err.message}`);
-          }
-          }
-        }
-      }
-    } catch (err) {
-      errorLog(`Failed to read directory ${dir}: ${err.message}`);
-    }
-  }
-
-  return null;
-}
-
-/**
- * Count task files in a plan's tasks directory
- * @param {string} planDir - Plan directory path
- * @returns {number} Number of task files found
- */
-function countTasks(planDir) {
-  const tasksDir = path.join(planDir, 'tasks');
-
-  if (!fs.existsSync(tasksDir)) {
-    return 0;
-  }
-
-  try {
-    const stats = fs.lstatSync(tasksDir);
-    if (!stats.isDirectory()) {
-      return 0;
-    }
-
-    const files = fs.readdirSync(tasksDir).filter(f => f.endsWith('.md'));
-    return files.length;
-  } catch (err) {
-    errorLog(`Failed to read tasks directory ${tasksDir}: ${err.message}`);
-    return 0;
-  }
-}
-
-/**
- * Check if execution blueprint section exists in plan file
- * @param {string} planFile - Path to plan file
- * @returns {boolean} True if blueprint section exists, false otherwise
- */
-function checkBlueprintExists(planFile) {
-  try {
-    const planContent = fs.readFileSync(planFile, 'utf8');
-    const blueprintExists = /^## Execution Blueprint/m.test(planContent);
-    return blueprintExists;
-  } catch (err) {
-    errorLog(`Failed to read plan file ${planFile}: ${err.message}`);
-    return false;
-  }
-}
-
 /**
  * List available plans for error messaging
+ * @private
+ * @param {string} [taskManagerRoot] - Optional task manager root path
  * @returns {string[]} Array of plan directory names
  */
-function listAvailablePlans() {
-  const taskManagerRoot = findTaskManagerRoot();
-
-  if (!taskManagerRoot) {
-    return [];
-  }
-
-  const plansDir = path.join(taskManagerRoot, 'plans');
-  const archiveDir = path.join(taskManagerRoot, 'archive');
-  const plans = [];
-
-  for (const dir of [plansDir, archiveDir]) {
-    if (!fs.existsSync(dir)) {
-      continue;
-    }
-
-    try {
-      const entries = fs.readdirSync(dir, { withFileTypes: true });
-      for (const entry of entries) {
-        if (entry.isDirectory() && entry.name.match(/^\d+--/)) {
-          plans.push(entry.name);
-        }
-      }
-    } catch (err) {
-      // Silently continue
-    }
-  }
-
-  return plans.sort((a, b) => {
-    const aId = parseInt(a.match(/^(\d+)--/)[1], 10);
-    const bId = parseInt(b.match(/^(\d+)--/)[1], 10);
-    return aId - bId;
-  });
+function _listAvailablePlans(taskManagerRoot) {
+  const plans = getAllPlans(taskManagerRoot);
+  return plans
+    .map(p => p.name)
+    .sort((a, b) => {
+      const aIdMatch = a.match(/^(\d+)--/);
+      const bIdMatch = b.match(/^(\d+)--/);
+      if (!aIdMatch || !bIdMatch) return 0;
+      return parseInt(aIdMatch[1], 10) - parseInt(bIdMatch[1], 10);
+    });
 }
 
 /**
  * Validate plan blueprint and output JSON or specific field
- * @param {string|number} planId - Plan ID to validate
- * @param {string} [fieldName] - Optional field name to extract (planFile, planDir, taskCount, blueprintExists)
+ * @private
+ * @param {string|number} inputId - Plan ID or absolute path to validate
+ * @param {string} [fieldName] - Optional field name to extract (planFile, planDir, taskCount, blueprintExists, taskManagerRoot, planId)
+ * @param {string} [startPath] - Optional start path for finding task manager root
  */
-function validatePlanBlueprint(planId, fieldName) {
-  if (!planId) {
-    errorLog('Plan ID is required');
-    errorLog('');
-    errorLog('Usage: node validate-plan-blueprint.cjs <plan-id> [field-name]');
-    errorLog('');
-    errorLog('Examples:');
-    errorLog('  node validate-plan-blueprint.cjs 47                  # Output full JSON');
-    errorLog('  node validate-plan-blueprint.cjs 47 planFile         # Output just the plan file path');
-    errorLog('  node validate-plan-blueprint.cjs 47 planDir          # Output just the plan directory');
-    errorLog('  node validate-plan-blueprint.cjs 47 taskCount        # Output just the task count');
-    errorLog('  node validate-plan-blueprint.cjs 47 blueprintExists  # Output yes/no');
+function _validatePlanBlueprint(inputId, fieldName, startPath = process.cwd()) {
+  if (!inputId) {
+    _errorLog('Plan ID or absolute path is required');
+    _errorLog('');
+    _errorLog('Usage: node validate-plan-blueprint.cjs <plan-id-or-path> [field-name]');
+    _errorLog('');
+    _errorLog('Examples:');
+    _errorLog('  node validate-plan-blueprint.cjs 47                  # Output full JSON');
+    _errorLog('  node validate-plan-blueprint.cjs /path/to/plan.md    # Output full JSON for specific file');
+    _errorLog('  node validate-plan-blueprint.cjs 47 planFile         # Output just the plan file path');
+    _errorLog('  node validate-plan-blueprint.cjs 47 blueprintExists  # Output yes/no');
+    process.exit(1);
+  }
+
+  // Check if input is numeric (allowing padded zeros) - if not a number or path, it's invalid
+  const numericInput = parseInt(inputId, 10);
+  const isNumeric = !isNaN(numericInput);
+  const isAbsolutePath = inputId.startsWith('/');
+
+  if (!isNumeric && !isAbsolutePath) {
+    _errorLog(`Invalid plan ID: "${inputId}" is not a valid number`);
     process.exit(1);
   }
 
-  const planInfo = findPlanById(planId);
+  const resolved = resolvePlan(inputId, startPath);
 
-  if (!planInfo) {
-    errorLog(`Plan ID ${planId} not found`);
-    errorLog('');
+  if (!resolved) {
+    _errorLog(`Plan ID ${inputId} not found or invalid`);
+    _errorLog('');
 
-    const availablePlans = listAvailablePlans();
+    const tmRoot = findTaskManagerRoot(startPath);
+    const availablePlans = _listAvailablePlans(tmRoot);
     if (availablePlans.length > 0) {
-      errorLog('Available plans:');
+      _errorLog('Available plans:');
       availablePlans.forEach(plan => {
-        errorLog(`  ${plan}`);
+        _errorLog(`  ${plan}`);
       });
-    } else {
-      errorLog('No plans found in .ai/task-manager/{plans,archive}/');
     }
 
-    errorLog('');
-    errorLog('Please verify:');
-    errorLog('  1. You are in the correct project directory');
-    errorLog('  2. The plan exists in .ai/task-manager/plans/ or .ai/task-manager/archive/');
-    errorLog('  3. The plan directory follows the naming pattern: [plan-id]--[name]');
-    errorLog('  4. The plan file follows the naming pattern: plan-[plan-id]--[name].md');
     process.exit(1);
   }
 
-  const { planFile, planDir } = planInfo;
+  const {
+    planFile,
+    planDir,
+    taskManagerRoot,
+    planId
+  } = resolved;
+
   const taskCount = countTasks(planDir);
   const blueprintExists = checkBlueprintExists(planFile);
 
   const result = {
     planFile,
     planDir,
+    taskManagerRoot,
+    planId,
     taskCount,
     blueprintExists: blueprintExists ? 'yes' : 'no'
   };
 
   // If field name is provided, output just that field
   if (fieldName) {
-    const validFields = ['planFile', 'planDir', 'taskCount', 'blueprintExists'];
+    const validFields = ['planFile', 'planDir', 'taskCount', 'blueprintExists', 'taskManagerRoot', 'planId'];
     if (!validFields.includes(fieldName)) {
-      errorLog(`Invalid field name: ${fieldName}`);
-      errorLog(`Valid fields: ${validFields.join(', ')}`);
+      _errorLog(`Invalid field name: ${fieldName}`);
+      _errorLog(`Valid fields: ${validFields.join(', ')}`);
       process.exit(1);
     }
     // Use process.stdout.write to avoid util.inspect colorization
-    // Convert to string explicitly to ensure plain text output
     process.stdout.write(String(result[fieldName]) + '\n');
   } else {
-    // Output full JSON for backward compatibility
+    // Output full JSON
     console.log(JSON.stringify(result, null, 2));
   }
 }
 
 // Main execution
-const planId = process.argv[2];
-const fieldName = process.argv[3];
-validatePlanBlueprint(planId, fieldName);
+if (require.main === module) {
+  const planId = process.argv[2];
+  const fieldName = process.argv[3];
+  _validatePlanBlueprint(planId, fieldName);
+}
+
+module.exports = {
+  _validatePlanBlueprint
+};

package/templates/assistant/commands/tasks/create-plan.md

@@ -4,8 +4,8 @@ description: Create a comprehensive plan to accomplish the request from the user
 ---
 # Comprehensive Plan Creation
 
-You are a strategic planning specialist who creates actionable plan documents that balance comprehensive context with 
-disciplined scope control. Your role is to think hard to create detailed, actionable plans based on user input while 
+You are a strategic planning specialist who creates actionable plan documents that balance comprehensive context with
+disciplined scope control. Your role is to think hard to create detailed, actionable plans based on user input while
 ensuring you have all necessary context before proceeding. Use the plan-creator sub-agent for this if it is available.
 
 ## Assistant Configuration
@@ -132,10 +132,22 @@ The schema for this frontmatter is:
 ```
 
 ### Plan ID Generation
-Execute this script to determine the plan ID:
+
+First, discover the task manager root directory:
+
+```bash
+root=$(node -e 'const fs=require("fs"),path=require("path");const f=p=>{const t=path.join(p,".ai/task-manager");const m=path.join(t,".init-metadata.json");try{if(JSON.parse(fs.readFileSync(m)).version){console.log(path.resolve(t));process.exit(0)}}catch(e){};const d=path.dirname(p);if(d!==p)f(d)};f(process.cwd());process.exit(1)')
+
+if [ -z "$root" ]; then
+    echo "Error: Could not find task manager root directory (.ai/task-manager)"
+    exit 1
+fi
+```
+
+Then execute this script to determine the plan ID:
 
 ```bash
-node .ai/task-manager/config/scripts/get-next-plan-id.cjs
+next_id=$(node $root/config/scripts/get-next-plan-id.cjs)
 ```
 
 **Key formatting:**

package/templates/assistant/commands/tasks/execute-blueprint.md

@@ -44,12 +44,25 @@ Before proceeding with execution, validate that tasks exist and the execution bl
 
 **Validation Steps:**
 
+First, discover the task manager root directory:
+
+```bash
+root=$(node -e 'const fs=require("fs"),path=require("path");const f=p=>{const t=path.join(p,".ai/task-manager");const m=path.join(t,".init-metadata.json");try{if(JSON.parse(fs.readFileSync(m)).version){console.log(path.resolve(t));process.exit(0)}}catch(e){};const d=path.dirname(p);if(d!==p)f(d)};f(process.cwd());process.exit(1)')
+
+if [ -z "$root" ]; then
+    echo "Error: Could not find task manager root directory (.ai/task-manager)"
+    exit 1
+fi
+```
+
+Then extract validation results:
+
 ```bash
 # Extract validation results directly from script
-plan_file=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs $1 planFile)
-plan_dir=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs $1 planDir)
-task_count=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs $1 taskCount)
-blueprint_exists=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs $1 blueprintExists)
+plan_file=$(node $root/config/scripts/validate-plan-blueprint.cjs $1 planFile)
+plan_dir=$(node $root/config/scripts/validate-plan-blueprint.cjs $1 planDir)
+task_count=$(node $root/config/scripts/validate-plan-blueprint.cjs $1 taskCount)
+blueprint_exists=$(node $root/config/scripts/validate-plan-blueprint.cjs $1 blueprintExists)
 ```
 
 4. **Automatic task generation**:

package/templates/assistant/commands/tasks/execute-task.md

@@ -57,21 +57,32 @@ fi
 
 ## Execution Process
 
-### 1. Plan and Task Location
+### 1. Root Discovery and Plan Location
 
-Locate the plan directory using the established find pattern:
+First, discover the task manager root directory:
+
+```bash
+root=$(node -e 'const fs=require("fs"),path=require("path");const f=p=>{const t=path.join(p,".ai/task-manager");const m=path.join(t,".init-metadata.json");try{if(JSON.parse(fs.readFileSync(m)).version){console.log(path.resolve(t));process.exit(0)}}catch(e){};const d=path.dirname(p);if(d!==p)f(d)};f(process.cwd());process.exit(1)')
+
+if [ -z "$root" ]; then
+    echo "Error: Could not find task manager root directory (.ai/task-manager)"
+    exit 1
+fi
+```
+
+Then locate the plan directory using the discovered root:
 
 ```bash
 plan_id="$1"
 task_id="$2"
 
 # Find plan directory
-plan_dir=$(find .ai/task-manager/{plans,archive} -type d -name "${plan_id}--*" 2>/dev/null | head -1)
+plan_dir=$(find $root/{plans,archive} -type d -name "${plan_id}--*" 2>/dev/null | head -1)
 
 if [ -z "$plan_dir" ]; then
     echo "Error: Plan with ID ${plan_id} not found"
     echo "Available plans:"
-    find .ai/task-manager/plans -name "*--*" -type d | head -5
+    find $root/plans -name "*--*" -type d | head -5
     exit 1
 fi
 
@@ -147,7 +158,7 @@ Use the dependency checking script to validate all dependencies:
 
 ```bash
 # Call the dependency checking script
-if ! node .ai/task-manager/config/scripts/check-task-dependencies.cjs "$plan_id" "$task_id"; then
+if ! node $root/config/scripts/check-task-dependencies.cjs "$plan_id" "$task_id"; then
     echo ""
     echo "Task execution blocked by unresolved dependencies."
     echo "Please complete the required dependencies first."

package/templates/assistant/commands/tasks/full-workflow.md

@@ -145,9 +145,20 @@ created: 2025-09-01
 
 #### Plan ID Generation
 
-**Auto-generate the next plan ID:**
+First, discover the task manager root directory:
+
+```bash
+root=$(node -e 'const fs=require("fs"),path=require("path");const f=p=>{const t=path.join(p,".ai/task-manager");const m=path.join(t,".init-metadata.json");try{if(JSON.parse(fs.readFileSync(m)).version){console.log(path.resolve(t));process.exit(0)}}catch(e){};const d=path.dirname(p);if(d!==p)f(d)};f(process.cwd());process.exit(1)')
+
+if [ -z "$root" ]; then
+    echo "Error: Could not find task manager root directory (.ai/task-manager)"
+    exit 1
+fi
+```
+
+Then auto-generate the next plan ID:
 ```bash
-node .ai/task-manager/config/scripts/get-next-plan-id.cjs
+node $root/config/scripts/get-next-plan-id.cjs
 ```
 
 **Key formatting:**
@@ -272,7 +283,7 @@ Use the task template in .ai/task-manager/config/templates/TASK_TEMPLATE.md
 When creating tasks, you need to determine the next available task ID for the specified plan. Use this bash command to automatically generate the correct ID:
 
 ```bash
-node .ai/task-manager/config/scripts/get-next-task-id.cjs [PLAN_ID from Step 1]
+node $root/config/scripts/get-next-task-id.cjs [PLAN_ID from Step 1]
 ```
 
 #### Step 4: POST_TASK_GENERATION_ALL hook
@@ -337,12 +348,14 @@ Before proceeding with execution, validate that tasks exist and the execution bl
 
 **Validation Steps:**
 
+Use the task manager root discovered in Step 1 to extract validation results:
+
 ```bash
 # Extract validation results directly from script
-plan_file=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs [planId] planFile)
-plan_dir=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs [planId] planDir)
-task_count=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs [planId] taskCount)
-blueprint_exists=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs [planId] blueprintExists)
+plan_file=$(node $root/config/scripts/validate-plan-blueprint.cjs [planId] planFile)
+plan_dir=$(node $root/config/scripts/validate-plan-blueprint.cjs [planId] planDir)
+task_count=$(node $root/config/scripts/validate-plan-blueprint.cjs [planId] taskCount)
+blueprint_exists=$(node $root/config/scripts/validate-plan-blueprint.cjs [planId] blueprintExists)
 ```
 
 If either `$task_count` is 0 or `$blueprint_exists` is "no":

package/templates/assistant/commands/tasks/generate-tasks.md

@@ -38,9 +38,22 @@ Use your internal Todo task tool to track the following process:
 
 - A plan document. Extract it with the following command.
 
+First, discover the task manager root directory:
+
+```bash
+root=$(node -e 'const fs=require("fs"),path=require("path");const f=p=>{const t=path.join(p,".ai/task-manager");const m=path.join(t,".init-metadata.json");try{if(JSON.parse(fs.readFileSync(m)).version){console.log(path.resolve(t));process.exit(0)}}catch(e){};const d=path.dirname(p);if(d!==p)f(d)};f(process.cwd());process.exit(1)')
+
+if [ -z "$root" ]; then
+    echo "Error: Could not find task manager root directory (.ai/task-manager)"
+    exit 1
+fi
+```
+
+Then extract validation results:
+
 ```bash
 # Extract validation results directly from script
-plan_file=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs $1 planFile)
+plan_file=$(node $root/config/scripts/validate-plan-blueprint.cjs $1 planFile)
 ```
 
 ### Input Error Handling
@@ -243,7 +256,7 @@ Use the task template in .ai/task-manager/config/templates/TASK_TEMPLATE.md
 When creating tasks, you need to determine the next available task ID for the specified plan. Use this bash command to automatically generate the correct ID:
 
 ```bash
-node .ai/task-manager/config/scripts/get-next-task-id.cjs $1
+node $root/config/scripts/get-next-task-id.cjs $1
 ```
 
 ### Validation Checklist

package/templates/assistant/commands/tasks/refine-plan.md

@@ -4,9 +4,9 @@ description: Review the plan with the provided ID, gather clarifications, and re
 ---
 # Plan Review and Refinement
 
-You are a strategic planning specialist who specializes in interrogating existing plans, uncovering blind spots, and 
-refining the document so that task generators receive the clearest possible instructions. Treat the current plan as the 
-work product of another assistant: your responsibility is to pressure test it, request any missing information from the 
+You are a strategic planning specialist who specializes in interrogating existing plans, uncovering blind spots, and
+refining the document so that task generators receive the clearest possible instructions. Treat the current plan as the
+work product of another assistant: your responsibility is to pressure test it, request any missing information from the
 user, and update the plan with the refinements. Use the plan-creator sub-agent for this if it is available.
 
 ## Assistant Configuration
@@ -34,11 +34,22 @@ If the plan ID is missing, immediately stop and show an error explaining correct
 
 ### Plan Discovery and Validation
 
-Obtain the plan using the plan ID using the following script:
+First, discover the task manager root directory:
+
+```bash
+root=$(node -e 'const fs=require("fs"),path=require("path");const f=p=>{const t=path.join(p,".ai/task-manager");const m=path.join(t,".init-metadata.json");try{if(JSON.parse(fs.readFileSync(m)).version){console.log(path.resolve(t));process.exit(0)}}catch(e){};const d=path.dirname(p);if(d!==p)f(d)};f(process.cwd());process.exit(1)')
+
+if [ -z "$root" ]; then
+    echo "Error: Could not find task manager root directory (.ai/task-manager)"
+    exit 1
+fi
+```
+
+Then obtain the plan using the plan ID:
 
 ```bash
 # Extract validation results directly from script
-plan_file=$(node .ai/task-manager/config/scripts/validate-plan-blueprint.cjs $1 planFile)
+plan_file=$(node $root/config/scripts/validate-plan-blueprint.cjs $1 planFile)
 ```
 
 ## Process Checklist