task-o-matic-core 0.1.0

package/src/lib/task-loop-execution.ts

@@ -0,0 +1,214 @@
+import type {
+  ExecuteLoopOptions,
+  ExecuteLoopResult,
+  Task,
+  TaskExecutionConfig,
+} from "../types";
+import { logger } from "./logger";
+import { sendNotifications } from "./notifications";
+import { taskService } from "../services/tasks";
+import { executeTaskCore } from "./task-execution-core";
+
+/**
+ * Execute multiple tasks in a loop with retry and verification
+ * This delegates to the unified executeTaskCore for each task
+ */
+export async function executeTaskLoop(
+  options: ExecuteLoopOptions
+): Promise<ExecuteLoopResult> {
+  const startTime = Date.now();
+  const { filters = {}, tool = "opencode", config = {}, dry = false } = options;
+
+  const {
+    maxRetries = 3,
+    verificationCommands = [],
+    autoCommit = false,
+    tryModels,
+    plan,
+    planModel,
+    reviewPlan,
+    review,
+    reviewModel,
+    customMessage,
+    continueSession,
+    model,
+    includeCompleted = false,
+    includePrd = false,
+    notifyTargets,
+  } = config;
+
+  logger.info("\n🔄 Starting Task Loop Execution\n");
+  logger.progress(`Executor Tool: ${tool}`);
+  if (model) logger.progress(`Executor Model: ${model}`);
+  logger.progress(`Max Retries per Task: ${maxRetries}`);
+  logger.progress(
+    `Verification Commands: ${
+      verificationCommands.length > 0
+        ? verificationCommands.join(", ")
+        : "None"
+    }`
+  );
+  logger.progress(`Auto Commit: ${autoCommit ? "Yes" : "No"}`);
+  logger.progress(`Dry Run: ${dry ? "Yes" : "No"}\n`);
+
+  // Get tasks to execute
+  let tasksToExecute: Task[] = [];
+
+  if (filters.taskIds && filters.taskIds.length > 0) {
+    // Execute specific tasks by ID
+    for (const taskId of filters.taskIds) {
+      const task = await taskService.getTask(taskId);
+      if (task) {
+        tasksToExecute.push(task);
+      } else {
+        logger.warn(`⚠️  Task ${taskId} not found, skipping`);
+      }
+    }
+  } else {
+    // Get all tasks matching filters
+    tasksToExecute = await taskService.listTasks({
+      status: filters.status,
+      tag: filters.tag,
+    });
+  }
+
+  // Filter out completed tasks unless includeCompleted is set
+  if (!includeCompleted) {
+    const beforeCount = tasksToExecute.length;
+    tasksToExecute = tasksToExecute.filter((t) => t.status !== "completed");
+    const filtered = beforeCount - tasksToExecute.length;
+    if (filtered > 0) {
+      logger.info(`   (Skipped ${filtered} already-completed task(s))\n`);
+    }
+  }
+
+  if (tasksToExecute.length === 0) {
+    logger.warn("⚠️  No tasks to execute (all may be completed)");
+    const emptyResult: ExecuteLoopResult = {
+      totalTasks: 0,
+      completedTasks: 0,
+      failedTasks: 0,
+      taskResults: [],
+      duration: Date.now() - startTime,
+    };
+    if (notifyTargets?.length)
+      await sendNotifications(notifyTargets, emptyResult);
+    return emptyResult;
+  }
+
+  logger.info(`📋 Found ${tasksToExecute.length} task(s) to execute\n`);
+
+  const taskResults: ExecuteLoopResult["taskResults"] = [];
+  let completedTasks = 0;
+  let failedTasks = 0;
+
+  // Execute tasks sequentially
+  for (let i = 0; i < tasksToExecute.length; i++) {
+    const task = tasksToExecute[i];
+
+    logger.info(
+      `\n${"=".repeat(60)}\n📌 Task ${i + 1}/${tasksToExecute.length}: ${
+        task.title
+      } (${task.id})\n${"=".repeat(60)}\n`
+    );
+
+    // Build unified task execution config
+    const taskConfig: TaskExecutionConfig = {
+      tool,
+      customMessage, // NEW: Support custom message override
+      executorConfig: {
+        continueLastSession: continueSession, // NEW: Support session continuation
+        model, // NEW: Pass model to executor
+      },
+      verificationCommands,
+      enableRetry: true, // Always enable retry in loop
+      maxRetries,
+      tryModels,
+      enablePlanPhase: plan,
+      planModel,
+      reviewPlan,
+      enableReviewPhase: review,
+      reviewModel,
+      autoCommit,
+      executeSubtasks: true, // Now supports subtasks!
+      includeCompleted, // Pass through to subtask execution
+      includePrd, // Pass through to execution core
+      dry,
+    };
+
+    try {
+      // Execute task using unified core
+      const result = await executeTaskCore(task.id, taskConfig);
+
+      // Check if task succeeded
+      const succeeded = result.success;
+
+      if (succeeded) {
+        completedTasks++;
+        logger.success(
+          `\n✅ Task ${task.title} completed successfully after ${result.attempts.length} attempt(s)\n`
+        );
+      } else {
+        failedTasks++;
+        logger.error(
+          `\n❌ Task ${task.title} failed after ${result.attempts.length} attempt(s)\n`
+        );
+      }
+
+      taskResults.push({
+        taskId: task.id,
+        taskTitle: task.title,
+        attempts: result.attempts,
+        finalStatus: succeeded ? "completed" : "failed",
+      });
+
+      // Stop the loop on first failure
+      if (!succeeded) {
+        break;
+      }
+    } catch (error) {
+      failedTasks++;
+      logger.error(
+        `\n❌ Task ${task.title} failed with error: ${
+          error instanceof Error ? error.message : "Unknown error"
+        }\n`
+      );
+
+      taskResults.push({
+        taskId: task.id,
+        taskTitle: task.title,
+        attempts: [],
+        finalStatus: "failed",
+      });
+
+      // Stop the loop on error
+      break;
+    }
+  }
+
+  const duration = Date.now() - startTime;
+
+  // Print summary
+  logger.info(
+    `\n${"=".repeat(60)}\n📊 Execution Summary\n${"=".repeat(60)}`
+  );
+  logger.progress(`Total Tasks: ${tasksToExecute.length}`);
+  logger.success(`✅ Completed: ${completedTasks}`);
+  logger.error(`❌ Failed: ${failedTasks}`);
+  logger.progress(`⏱  Duration: ${(duration / 1000).toFixed(2)} seconds\n`);
+
+  const result: ExecuteLoopResult = {
+    totalTasks: tasksToExecute.length,
+    completedTasks,
+    failedTasks,
+    taskResults,
+    duration,
+  };
+
+  // Send notifications if configured
+  if (notifyTargets?.length) {
+    await sendNotifications(notifyTargets, result);
+  }
+
+  return result;
+}

package/src/lib/task-planning.ts

@@ -0,0 +1,157 @@
+import { logger } from "./logger";
+import { ExecutorFactory } from "./executors/executor-factory";
+import { ExecutorConfig, ExecutorTool, Task } from "../types";
+import { existsSync, readFileSync } from "fs";
+
+import { exec } from "child_process";
+import { promisify } from "util";
+import { commitFile } from "./git-utils";
+
+const execAsync = promisify(exec);
+
+/**
+ * Planning phase configuration
+ */
+export interface PlanningConfig {
+  planModel?: string; // Format: "executor:model" or just "model"
+  reviewPlan?: boolean; // Enable human review loop
+  autoCommit?: boolean; // Auto-commit the plan file
+  dry?: boolean; // Dry run mode
+  onPlanReview?: (planFile: string) => Promise<string | undefined>; // Callback for review
+}
+
+/**
+ * Planning phase result
+ */
+export interface PlanningResult {
+  planContent?: string;
+  planFileName?: string;
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Execute planning phase for a task
+ * Creates an AI-generated implementation plan with optional human review
+ */
+export async function executePlanningPhase(
+  task: Task,
+  defaultTool: ExecutorTool,
+  config: PlanningConfig,
+  execFn: (
+    command: string
+  ) => Promise<{ stdout: string; stderr: string }> = execAsync
+): Promise<PlanningResult> {
+  const { planModel, reviewPlan, autoCommit, dry, onPlanReview } = config;
+
+  logger.info(`\n🧠 Starting Planning Phase for Task: ${task.title}`);
+
+  const planFileName = `task-${task.id}-plan.md`;
+
+  // Parse executor and model from planModel string
+  const planExecutor = planModel
+    ? (planModel.split(":")[0] as ExecutorTool)
+    : defaultTool;
+  const planModelName = planModel ? planModel.split(":")[1] : undefined;
+
+  let planningPrompt = `You are a senior software architect. Analyze the following task and create a detailed implementation plan.
+
+Task: ${task.title}
+Description: ${task.description || "No description provided."}
+
+Requirements:
+1. Analyze the task requirements.
+2. Create a detailed step-by-step implementation plan.
+3. Identify necessary file changes.
+4. Write this plan to a file named "${planFileName}" in the current directory.
+5. Do NOT implement the code yet, just create the plan file.
+
+Please create the "${planFileName}" file now.`;
+
+  logger.progress(
+    `   Using executor for planning: ${planExecutor}${
+      planModelName ? ` (${planModelName})` : ""
+    }`
+  );
+
+  // Create executor for planning
+  const planningConfig: ExecutorConfig = {
+    model: planModelName,
+    continueLastSession: false,
+  };
+
+  const executor = ExecutorFactory.create(planExecutor, planningConfig);
+
+  try {
+    let planningComplete = false;
+    let planContent: string | undefined;
+
+    while (!planningComplete) {
+      await executor.execute(planningPrompt, dry, planningConfig);
+
+      if (!dry) {
+        // Verify plan file exists and read it
+        if (existsSync(planFileName)) {
+          planContent = readFileSync(planFileName, "utf-8");
+          logger.success(`✅ Plan created successfully: ${planFileName}`);
+
+          // Human Review Loop
+          if (reviewPlan) {
+            if (onPlanReview) {
+              logger.warn(
+                `\n👀 Pausing for Human Review of the Plan: ${planFileName}`
+              );
+
+              const feedback = await onPlanReview(planFileName);
+
+              if (feedback && feedback.trim() !== "") {
+                logger.info("🔄 Refining plan based on feedback...");
+                planningPrompt = `The user provided the following feedback on the plan you just created:
+
+"${feedback}"
+
+Please update the plan file "${planFileName}" to incorporate this feedback.`;
+                // Continue loop to regenerate plan
+                continue;
+              }
+            } else {
+              logger.warn("Review requested but no review callback provided.");
+            }
+          }
+
+          // Auto-commit plan if enabled (only after approval)
+          if (autoCommit) {
+            await commitFile(
+              planFileName,
+              `docs: create implementation plan for task ${task.id}`,
+              execFn
+            );
+          }
+
+          planningComplete = true;
+        } else {
+          logger.warn(
+            `⚠️  Plan file ${planFileName} was not created by the executor.`
+          );
+          planningComplete = true; // Exit loop to avoid infinite retry if file not created
+        }
+      } else {
+        planningComplete = true; // Dry run
+      }
+    }
+
+    return {
+      planContent,
+      planFileName,
+      success: true,
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.error(`❌ Planning phase failed: ${errorMessage}`);
+
+    return {
+      success: false,
+      error: errorMessage,
+    };
+  }
+}

package/src/lib/task-review.ts

@@ -0,0 +1,138 @@
+import { logger } from "./logger";
+import { ExecutorTool, Task } from "../types";
+import { getAIOperations } from "../utils/ai-service-factory";
+import { exec } from "child_process";
+import { promisify } from "util";
+
+const execAsync = promisify(exec);
+
+/**
+ * Review phase configuration
+ */
+export interface ReviewConfig {
+  reviewModel?: string; // Format: "executor:model" or just "model"
+  planContent?: string; // Plan content to include in review context
+  dry?: boolean; // Dry run mode
+}
+
+/**
+ * Review phase result
+ */
+export interface ReviewResult {
+  approved: boolean;
+  feedback: string;
+  success: boolean;
+  error?: string;
+}
+
+/**
+ * Execute AI review phase for task execution
+ * Reviews code changes and provides feedback
+ */
+export async function executeReviewPhase(
+  task: Task,
+  config: ReviewConfig,
+  execFn: (
+    command: string
+  ) => Promise<{ stdout: string; stderr: string }> = execAsync
+): Promise<ReviewResult> {
+  const { reviewModel, planContent, dry } = config;
+
+  logger.info("\n🕵️  Starting AI Review Phase...");
+
+  if (dry) {
+    logger.warn("🔍 DRY RUN - Review phase skipped");
+    return {
+      approved: true,
+      feedback: "Dry run - review skipped",
+      success: true,
+    };
+  }
+
+  try {
+    // Get git diff
+    const { stdout: diff } = await execFn("git diff HEAD");
+
+    if (!diff.trim()) {
+      logger.warn("⚠️  No changes detected to review.");
+      return {
+        approved: true,
+        feedback: "No changes to review",
+        success: true,
+      };
+    }
+
+    // Parse executor and model from reviewModel string
+    const reviewExecutor = reviewModel
+      ? (reviewModel.split(":")[0] as ExecutorTool)
+      : undefined;
+    const reviewModelName = reviewModel ? reviewModel.split(":")[1] : undefined;
+
+    if (reviewExecutor && reviewModelName) {
+      logger.progress(
+        `   Using executor for review: ${reviewExecutor} (${reviewModelName})`
+      );
+    } else {
+      logger.progress("   Using default AI provider for review");
+    }
+
+    const reviewPrompt = `You are a strict code reviewer. Review the following changes for the task.
+
+Task: ${task.title}
+${planContent ? `Plan: ${planContent}` : "Plan: No plan provided."}
+
+Git Diff:
+${diff.substring(0, 10000)}
+
+Analyze the changes for:
+1. Correctness (does it solve the task?)
+2. Code Quality (clean code, best practices)
+3. Potential Bugs
+
+Return a JSON object:
+{
+  "approved": boolean,
+  "feedback": "Detailed feedback explaining why it was rejected or approved"
+}
+`;
+
+    // Use AI operations to get review response
+    const aiOps = getAIOperations();
+    const aiResponse = await aiOps.streamText(reviewPrompt);
+    const jsonMatch = aiResponse.match(/\{[\s\S]*\}/);
+
+    if (jsonMatch) {
+      const reviewResult = JSON.parse(jsonMatch[0]);
+
+      if (!reviewResult.approved) {
+        logger.error(`❌ AI Review Rejected Changes: ${reviewResult.feedback}`);
+      } else {
+        logger.success(`✅ AI Review Approved: ${reviewResult.feedback}`);
+      }
+
+      return {
+        approved: reviewResult.approved,
+        feedback: reviewResult.feedback,
+        success: true,
+      };
+    } else {
+      logger.warn("⚠️  Could not parse AI review response. Assuming approval.");
+      return {
+        approved: true,
+        feedback: "Could not parse review response, assuming approval",
+        success: true,
+      };
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.error(`❌ AI Review failed: ${errorMessage}`);
+
+    // If review crashes, warn but don't fail the task
+    return {
+      approved: true,
+      feedback: `Review failed: ${errorMessage}`,
+      success: false,
+      error: errorMessage,
+    };
+  }
+}

package/src/lib/validation.ts

@@ -0,0 +1,140 @@
+import { exec } from "child_process";
+import { promisify } from "util";
+import { logger } from "./logger";
+import { AIConfig } from "../types";
+
+const execAsync = promisify(exec);
+
+/**
+ * Validation/Verification result for a single command
+ */
+export interface ValidationResult {
+  command: string;
+  success: boolean;
+  output?: string;
+  error?: string;
+}
+
+/**
+ * Format verification error for AI feedback
+ * Produces a structured message that AI can easily parse and act upon
+ */
+export function formatVerificationError(result: ValidationResult): string {
+  return `## Verification Failed: ${result.command}
+
+**Error Output**:
+\`\`\`
+${result.error || "No error output captured"}
+\`\`\`
+
+Please analyze this error carefully and fix the issue. Common causes include:
+- Syntax errors in the code
+- Type errors (missing types, wrong types)
+- Missing imports or dependencies
+- Logic errors or incorrect implementations
+- Build configuration issues`;
+}
+
+export function isValidAIProvider(
+  provider: string
+): provider is NonNullable<AIConfig["provider"]> {
+  return ["openrouter", "openai", "anthropic", "custom"].includes(provider);
+}
+
+/**
+ * Run validation/verification commands and return results
+ * Supports both --validate and --verify as aliases
+ * Returns detailed results for each command
+ */
+export async function runValidations(
+  validations: string[],
+  dry: boolean,
+  execFn: (
+    command: string
+  ) => Promise<{ stdout: string; stderr: string }> = execAsync
+): Promise<ValidationResult[]> {
+  const results: ValidationResult[] = [];
+
+  if (validations.length === 0) {
+    return results;
+  }
+
+  if (dry) {
+    logger.warn(
+      "🔍 DRY RUN - Validation/verification commands that would run:"
+    );
+    validations.forEach((cmd) => {
+      logger.progress(`  ${cmd}`);
+      results.push({
+        command: cmd,
+        success: true,
+        output: "DRY RUN - not executed",
+      });
+    });
+    return results;
+  }
+
+  logger.info(
+    `🧪 Running ${validations.length} validation/verification command${
+      validations.length > 1 ? "s" : ""
+    }...`
+  );
+
+  for (let i = 0; i < validations.length; i++) {
+    const validation = validations[i];
+    logger.info(
+      `🧪 Running validation [${i + 1}/${validations.length}]: ${validation}`
+    );
+
+    try {
+      const { stdout, stderr } = await execFn(validation);
+      logger.success(`✅ Validation passed: ${validation}`);
+
+      // Show stdout if there's any output
+      if (stdout && stdout.trim()) {
+        logger.progress(`   Output: ${stdout.trim()}`);
+      }
+
+      results.push({
+        command: validation,
+        success: true,
+        output: stdout.trim(),
+      });
+    } catch (error: any) {
+      logger.error(`❌ Validation failed: ${validation}`);
+
+      const errorOutput = error.stderr || error.stdout || error.message;
+
+      // Show error details
+      if (error.stdout && error.stdout.trim()) {
+        logger.warn(`   stdout: ${error.stdout.trim()}`);
+      }
+      if (error.stderr && error.stderr.trim()) {
+        logger.error(`   stderr: ${error.stderr.trim()}`);
+      }
+      if (error.message) {
+        logger.error(`   Error: ${error.message}`);
+      }
+
+      results.push({
+        command: validation,
+        success: false,
+        error: errorOutput,
+      });
+
+      // Return early on first failure
+      break;
+    }
+  }
+
+  const allPassed = results.every((r) => r.success);
+  if (allPassed) {
+    logger.success(
+      `🎉 All ${validations.length} validation${
+        validations.length > 1 ? "s" : ""
+      } passed!`
+    );
+  }
+
+  return results;
+}

package/src/prompts/documentation-detection.ts

@@ -0,0 +1,21 @@
+export const DOCUMENTATION_DETECTION_PROMPT = `You are an expert developer. Your job is to analyze a task and fetch relevant documentation using Context7 and create a dedicated documentation for the task.
+
+Do not create a plan, i want a documentation for the actual task using the knowledge you gained from the research.
+
+## Task:
+**Title**: {TASK_TITLE}
+**Description**: {TASK_DESCRIPTION}
+
+## Current Stack:
+{STACK_INFO}
+
+## Already Researched:
+{EXISTING_RESEARCH}
+
+## Instructions:
+1. Identify technologies/libraries mentioned in the task that need documentation
+2. Skip anything already covered in existing research
+3. Use Context7 to resolve library names and fetch documentation
+4. Create a focused documentation only on what's actually needed for this specific task
+
+Get the documentation libraries needed for this task.`;

package/src/prompts/documentation-recap.ts

@@ -0,0 +1,11 @@
+export const DOCUMENTATION_RECAP_PROMPT = `Create a concise recap of the documentation fetched for these libraries:
+
+Libraries:
+{LIBRARIES_LIST}
+
+Documentation Contents:
+{DOCUMENTATION_CONTENTS}
+
+Please provide a 2-3 sentence summary of what documentation is available and how it relates to the task.`;
+
+export const DOCUMENTATION_RECAP_SYSTEM_PROMPT = `You are a technical writer who creates concise summaries of documentation collections.`;

package/src/prompts/index.ts

@@ -0,0 +1,14 @@
+export * from "./prd-parsing";
+export * from "./task-breakdown";
+export * from "./task-enhancement";
+export * from "./prd-rework";
+export * from "./documentation-detection";
+export * from "./task-planning";
+export * from "./task-execution";
+export * from "./prd-question";
+export * from "./prd-generation";
+export * from "./prd-combination";
+export * from "./documentation-recap";
+export * from "./prd-question-answer";
+export * from "./workflow-prompts";
+export * from "./prd-suggest-stack";