@arvorco/relentless 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -7,7 +7,43 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0](https://github.com/ArvorCo/Relentless/releases/tag/v0.6.0) - 2026-01-23
+
+### Major Features
+
+#### Claude Code Tasks Integration - Cross-Session Coordination (#8)
+- **TaskList-Per-Feature**: Each feature gets its own TaskList ID (e.g., `relentless-auth`)
+- **Bidirectional Sync**: Convert PRD user stories ↔ Claude Tasks
+- **Cross-session sharing**: Multiple Claude instances coordinate via `CLAUDE_CODE_TASK_LIST_ID` env var
+- **New `--tasks` flag**: Enable Tasks integration with `relentless run --feature auth --tasks`
+
+#### New Tasks Module (`src/tasks/`)
+- `types.ts` - Task types and Zod schemas (`ClaudeTask`, `TaskList`, `SyncResult`, `ImportResult`)
+- `tasklist.ts` - TaskList CRUD operations (create, load, save, delete, addTask, updateTask, etc.)
+- `sync.ts` - Bidirectional sync: `syncPrdToTasks()`, `syncTasksToPrd()`, `importTasksToPrd()`, `bidirectionalSync()`
+- `index.ts` - Module exports
+
+#### New CLI Commands
+```bash
+# Run with Tasks integration
+relentless run --feature auth --tasks
+
+# Task management
+relentless tasks list -f <feature>    # List tasks for a feature
+relentless tasks sync -f <feature>    # Sync PRD ↔ Claude Tasks
+relentless tasks import <id> -f <feature>  # Import Claude Tasks to PRD
+relentless tasks clear -f <feature>   # Clear TaskList
+```
+
+### Added
+- `taskListId` option in `InvokeOptions` for agent adapters
+- `env` option in `RunCommandOptions` for passing environment variables
+- 38 new tests for Tasks module (types + tasklist CRUD)
+
 ### Fixed
+- **Rate Limit Detection**: Fixed false positive when Claude mentions "model" and "not_found_error" in conversation
+  - Previous pattern was too broad and matched normal Claude output
+  - Now uses specific pattern for actual API error responses
 - **Commands**: Use abstract `[skills_path]` pattern for cross-agent compatibility (#7)
   - Commands now reference `[skills_path]/skillname/SKILL.md` instead of hardcoded `.claude/skills/`
   - Each agent can resolve the path to their own skills directory
@@ -474,7 +510,9 @@ Relentless evolved from the [Ralph Wiggum Pattern](https://ghuntley.com/ralph/)
 - **License**: MIT
 - **Inspiration**: [Ralph Wiggum Pattern](https://ghuntley.com/ralph/) by Geoffrey Huntley
 
-[Unreleased]: https://github.com/ArvorCo/Relentless/compare/v0.5.2...HEAD
+[Unreleased]: https://github.com/ArvorCo/Relentless/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/ArvorCo/Relentless/compare/v0.5.3...v0.6.0
+[0.5.3]: https://github.com/ArvorCo/Relentless/compare/v0.5.2...v0.5.3
 [0.5.2]: https://github.com/ArvorCo/Relentless/compare/v0.5.1...v0.5.2
 [0.5.1]: https://github.com/ArvorCo/Relentless/compare/v0.5.0...v0.5.1
 [0.5.0]: https://github.com/ArvorCo/Relentless/compare/v0.4.5...v0.5.0

package/bin/relentless.ts

@@ -64,6 +64,7 @@ program
   .option("--review-mode <mode>", `Review quality mode (${VALID_REVIEW_MODES.join(", ")})`)
   .option("--dry-run", "Show what would be executed without running", false)
   .option("--tui", "Use beautiful terminal UI interface", false)
+  .option("--tasks", "Enable Claude Code Tasks integration for cross-session coordination", false)
   .option("-d, --dir <path>", "Working directory", process.cwd())
   .action(async (options) => {
     // Load config first to get defaultAgent
@@ -200,6 +201,8 @@ program
       fallbackOrder,
       skipReview,
       reviewMode,
+      enableTasks: options.tasks,
+      featureName: options.feature,
     });
 
     if (result.success) {
@@ -747,6 +750,167 @@ queue
     }
   });
 
+// Tasks commands - Claude Code Tasks integration
+const tasks = program.command("tasks").description("Manage Claude Code Tasks for cross-session coordination");
+
+tasks
+  .command("list")
+  .description("List tasks for a feature")
+  .requiredOption("-f, --feature <name>", "Feature name")
+  .option("-d, --dir <path>", "Project directory", process.cwd())
+  .action(async (options) => {
+    const { generateTaskListId, loadTaskList, getTaskListSummary } = await import("../src/tasks");
+
+    const taskListId = generateTaskListId(options.feature);
+    const taskList = await loadTaskList(taskListId);
+
+    if (!taskList) {
+      console.log(chalk.dim(`\nNo task list found for feature: ${options.feature}`));
+      console.log(chalk.dim(`Run 'relentless run --feature ${options.feature} --tasks' to create one.\n`));
+      return;
+    }
+
+    const summary = await getTaskListSummary(taskListId);
+    if (!summary) {
+      console.log(chalk.dim(`\nNo task list found for feature: ${options.feature}\n`));
+      return;
+    }
+
+    console.log(chalk.bold(`\n📋 Tasks: ${options.feature}\n`));
+    console.log(chalk.dim(`TaskList ID: ${taskListId}`));
+    console.log(chalk.dim(`Progress: ${summary.completedTasks}/${summary.totalTasks} complete\n`));
+
+    for (const task of taskList.tasks) {
+      const status = task.status === "completed"
+        ? chalk.green("✓")
+        : task.status === "in_progress"
+          ? chalk.yellow("◐")
+          : chalk.dim("○");
+      const content = task.status === "completed"
+        ? chalk.strikethrough(chalk.dim(task.content))
+        : task.content;
+      console.log(`  ${status} ${content}`);
+    }
+    console.log("");
+  });
+
+tasks
+  .command("sync")
+  .description("Sync PRD stories with Claude Tasks")
+  .requiredOption("-f, --feature <name>", "Feature name")
+  .option("-d, --dir <path>", "Project directory", process.cwd())
+  .action(async (options) => {
+    const { bidirectionalSync } = await import("../src/tasks");
+
+    const relentlessDir = findRelentlessDir(options.dir);
+    if (!relentlessDir) {
+      console.error(chalk.red("Relentless not initialized. Run: relentless init"));
+      process.exit(1);
+    }
+
+    const featureDir = join(relentlessDir, "features", options.feature);
+    const prdPath = join(featureDir, "prd.json");
+
+    if (!existsSync(prdPath)) {
+      console.error(chalk.red(`Feature '${options.feature}' not found or has no prd.json`));
+      console.log(chalk.dim(`Available features: ${listFeatures(options.dir).join(", ") || "none"}`));
+      process.exit(1);
+    }
+
+    console.log(chalk.dim(`Syncing tasks for ${options.feature}...`));
+
+    const result = await bidirectionalSync(prdPath, options.feature);
+
+    if (result.success) {
+      console.log(chalk.green(`\n✓ Sync complete`));
+      if (result.added > 0) {
+        console.log(chalk.dim(`  Added: ${result.added} tasks`));
+      }
+      if (result.updated > 0) {
+        console.log(chalk.dim(`  Updated: ${result.updated} tasks`));
+      }
+      if (result.removed > 0) {
+        console.log(chalk.dim(`  Removed: ${result.removed} tasks`));
+      }
+    } else {
+      console.error(chalk.red(`\n❌ Sync failed`));
+      for (const error of result.errors) {
+        console.error(chalk.red(`  ${error}`));
+      }
+      process.exit(1);
+    }
+
+    for (const warning of result.warnings) {
+      console.log(chalk.yellow(`  ⚠️  ${warning}`));
+    }
+    console.log("");
+  });
+
+tasks
+  .command("import <taskListId>")
+  .description("Import Claude Tasks to create a new PRD")
+  .requiredOption("-f, --feature <name>", "Feature name for the new PRD")
+  .option("-d, --dir <path>", "Project directory", process.cwd())
+  .action(async (taskListId, options) => {
+    const { importTasksToPrd } = await import("../src/tasks");
+
+    const relentlessDir = findRelentlessDir(options.dir);
+    if (!relentlessDir) {
+      console.error(chalk.red("Relentless not initialized. Run: relentless init"));
+      process.exit(1);
+    }
+
+    // Create feature directory if it doesn't exist
+    const featureDir = join(relentlessDir, "features", options.feature);
+    if (!existsSync(featureDir)) {
+      mkdirSync(featureDir, { recursive: true });
+    }
+
+    console.log(chalk.dim(`Importing tasks from ${taskListId}...`));
+
+    const result = await importTasksToPrd(taskListId, options.feature, featureDir);
+
+    if (result.success) {
+      console.log(chalk.green(`\n✓ Import complete`));
+      console.log(chalk.dim(`  Created ${result.storiesCreated} stories`));
+      console.log(chalk.dim(`  PRD saved to: ${result.prdPath}`));
+      console.log(chalk.dim(`\nNext step:`));
+      console.log(chalk.cyan(`  relentless run --feature ${options.feature} --tasks`));
+    } else {
+      console.error(chalk.red(`\n❌ Import failed`));
+      for (const error of result.errors) {
+        console.error(chalk.red(`  ${error}`));
+      }
+      process.exit(1);
+    }
+    console.log("");
+  });
+
+tasks
+  .command("clear")
+  .description("Clear all tasks for a feature")
+  .requiredOption("-f, --feature <name>", "Feature name")
+  .option("-d, --dir <path>", "Project directory", process.cwd())
+  .action(async (options) => {
+    const { generateTaskListId, clearTaskList, taskListExists } = await import("../src/tasks");
+
+    const taskListId = generateTaskListId(options.feature);
+
+    if (!await taskListExists(taskListId)) {
+      console.log(chalk.dim(`\nNo task list found for feature: ${options.feature}\n`));
+      return;
+    }
+
+    const cleared = await clearTaskList(taskListId);
+
+    if (cleared) {
+      console.log(chalk.green(`\n✓ Cleared all tasks for ${options.feature}\n`));
+    } else {
+      console.error(chalk.red(`\n❌ Failed to clear tasks\n`));
+      process.exit(1);
+    }
+  });
+
 // Analyze command
 program
   .command("analyze")

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arvorco/relentless",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Universal AI agent orchestrator - works with Claude Code, Amp, OpenCode, Codex, Droid, and Gemini",
   "type": "module",
   "publishConfig": {

package/src/agents/claude.ts

@@ -79,10 +79,17 @@ export const claudeAdapter: AgentAdapter = {
       }
     }
 
+    // Build environment variables
+    const env: Record<string, string> = {};
+    if (options?.taskListId) {
+      env.CLAUDE_CODE_TASK_LIST_ID = options.taskListId;
+    }
+
     const result = await runCommand(["claude", ...args], {
       cwd: options?.workingDirectory,
       stdin: new Blob([prompt]),
       timeoutMs: options?.timeout,
+      env: Object.keys(env).length > 0 ? env : undefined,
     });
 
     const timeoutNote =
@@ -120,11 +127,20 @@ export const claudeAdapter: AgentAdapter = {
       }
     }
 
+    // Build environment variables for streaming
+    const streamEnv: Record<string, string> = {};
+    if (options?.taskListId) {
+      streamEnv.CLAUDE_CODE_TASK_LIST_ID = options.taskListId;
+    }
+
     const proc = Bun.spawn(["claude", ...args], {
       cwd: options?.workingDirectory,
       stdin: new Blob([prompt]),
       stdout: "pipe",
       stderr: "pipe",
+      env: Object.keys(streamEnv).length > 0
+        ? { ...process.env, ...streamEnv }
+        : undefined,
     });
 
     const decoder = new TextDecoder();
@@ -178,7 +194,9 @@ export const claudeAdapter: AgentAdapter = {
       };
     }
 
-    if (/not_found_error/i.test(output) && /model/i.test(output)) {
+    // More specific pattern for actual API model not found errors
+    // Avoid matching if Claude just mentions "model" and "not_found_error" in conversation
+    if (/error.*model.*not[_\s]?found|model.*not[_\s]?found.*error|"type":\s*"not_found_error"/i.test(output)) {
       return {
         limited: true,
         message: "Claude model not found",

package/src/agents/exec.ts

@@ -6,6 +6,8 @@ export interface RunCommandOptions {
   cwd?: string;
   stdin?: Blob;
   timeoutMs?: number;
+  /** Environment variables to pass to the command */
+  env?: Record<string, string>;
 }
 
 export interface RunCommandResult {
@@ -48,11 +50,18 @@ export async function runCommand(
   options: RunCommandOptions = {}
 ): Promise<RunCommandResult> {
   const startTime = Date.now();
+
+  // Merge custom env vars with current process env
+  const env = options.env
+    ? { ...process.env, ...options.env }
+    : undefined;
+
   const proc = Bun.spawn(command, {
     cwd: options.cwd,
     stdin: options.stdin,
     stdout: "pipe",
     stderr: "pipe",
+    env,
   });
 
   let lastOutput = Date.now();

package/src/agents/types.ts

@@ -16,6 +16,8 @@ export interface InvokeOptions {
   model?: string;
   /** Skip all permission prompts */
   dangerouslyAllowAll?: boolean;
+  /** Claude Code TaskList ID for cross-session coordination */
+  taskListId?: string;
 }
 
 /**

package/src/execution/runner.ts

@@ -42,6 +42,7 @@ import {
   logSkipRejectedToProgress,
   formatSkipMessage,
 } from "./commands";
+import { generateTaskListId, syncPrdToTasks, syncTasksToPrd } from "../tasks";
 
 export interface RunOptions {
   /** Agent to use (or "auto" for smart routing) */
@@ -66,6 +67,10 @@ export interface RunOptions {
   skipReview?: boolean;
   /** Review quality mode (can differ from execution mode) */
   reviewMode?: "free" | "cheap" | "good" | "genius";
+  /** Enable Claude Code Tasks integration for cross-session coordination */
+  enableTasks?: boolean;
+  /** Feature name (for TaskList ID generation) */
+  featureName?: string;
 }
 
 export interface RunResult {
@@ -479,6 +484,23 @@ export async function run(options: RunOptions): Promise<RunResult> {
     console.log(chalk.yellow("\n⚠️  Dry run mode - not executing\n"));
   }
 
+  // Generate TaskList ID if tasks integration is enabled
+  let taskListId: string | undefined;
+  if (options.enableTasks && options.featureName) {
+    taskListId = generateTaskListId(options.featureName);
+    console.log(`Tasks: ${chalk.green("enabled")} (${taskListId})`);
+
+    // Sync PRD to tasks at start
+    try {
+      const syncResult = await syncPrdToTasks(prd, options.featureName);
+      if (syncResult.added > 0 || syncResult.updated > 0) {
+        console.log(chalk.dim(`  Synced ${syncResult.added} new, ${syncResult.updated} updated tasks`));
+      }
+    } catch (syncError) {
+      console.warn(chalk.yellow(`  ⚠️  Failed to sync PRD to tasks: ${syncError}`));
+    }
+  }
+
   // Main loop
   for (let i = 1; i <= options.maxIterations; i++) {
     iterations = i;
@@ -737,6 +759,7 @@ export async function run(options: RunOptions): Promise<RunResult> {
           dangerouslyAllowAll: options.config.agents[agent.name]?.dangerouslyAllowAll ?? true,
           model: autoModeEnabled ? autoRoutingModel : options.config.agents[agent.name]?.model,
           timeout: options.config.execution.timeout,
+          taskListId,
         });
 
         // Check for rate limit during research phase
@@ -798,6 +821,7 @@ export async function run(options: RunOptions): Promise<RunResult> {
         dangerouslyAllowAll: options.config.agents[agent.name]?.dangerouslyAllowAll ?? true,
         model: autoModeEnabled ? autoRoutingModel : options.config.agents[agent.name]?.model,
         timeout: options.config.execution.timeout,
+        taskListId,
       });
 
       // Check for rate limit
@@ -942,6 +966,18 @@ export async function run(options: RunOptions): Promise<RunResult> {
   const success = isComplete(finalPRD);
   const duration = Date.now() - startTime;
 
+  // Final sync tasks back to PRD
+  if (options.enableTasks && options.featureName) {
+    try {
+      const syncResult = await syncTasksToPrd(options.prdPath, options.featureName);
+      if (syncResult.updated > 0) {
+        console.log(chalk.dim(`  Synced ${syncResult.updated} task updates back to PRD`));
+      }
+    } catch (syncError) {
+      console.warn(chalk.yellow(`  ⚠️  Failed to sync tasks to PRD: ${syncError}`));
+    }
+  }
+
   if (!success) {
     console.log(chalk.yellow(`\n⚠️  Reached max iterations (${options.maxIterations}) without completing all stories.`));
     console.log(chalk.dim(`Check progress.txt for status.`));

package/src/tasks/index.ts

@@ -0,0 +1,79 @@
+/**
+ * Claude Code Tasks Module
+ *
+ * Integration with Claude Code's native Tasks feature for cross-session
+ * coordination and parallel story execution.
+ *
+ * ## Usage
+ *
+ * ### Enable TaskList for a feature
+ * ```bash
+ * relentless run --feature auth --tasks
+ * # Sets CLAUDE_CODE_TASK_LIST_ID=relentless-auth
+ * ```
+ *
+ * ### Sync PRD to Tasks
+ * ```bash
+ * relentless tasks sync -f auth
+ * ```
+ *
+ * ### Import Claude Tasks to PRD
+ * ```bash
+ * relentless tasks import my-task-list --feature my-feature
+ * ```
+ *
+ * ## Key Concepts
+ *
+ * - **TaskList**: A collection of tasks stored in ~/.claude/tasks/{id}.json
+ * - **Task**: Individual work item with status, dependencies, and story link
+ * - **Sync**: Bidirectional sync between PRD stories and Claude Tasks
+ *
+ * @see https://docs.anthropic.com/claude-code
+ */
+
+// Types
+export {
+  type TaskStatus,
+  type ClaudeTask,
+  type TaskList,
+  type TaskListSummary,
+  type SyncResult,
+  type ImportResult,
+  ClaudeTaskSchema,
+  TaskListSchema,
+  generateTaskListId,
+  getTasksDirectory,
+  getTaskListPath,
+} from "./types";
+
+// TaskList CRUD operations
+export {
+  ensureTasksDirectory,
+  taskListExists,
+  loadTaskList,
+  saveTaskList,
+  createTaskList,
+  deleteTaskList,
+  listTaskLists,
+  getTaskListSummary,
+  addTask,
+  updateTask,
+  removeTask,
+  markTaskComplete,
+  markTaskInProgress,
+  getNextTask,
+  getParallelTasks,
+  isTaskListComplete,
+  clearTaskList,
+  getOrCreateTaskList,
+} from "./tasklist";
+
+// PRD Sync operations
+export {
+  storyToTask,
+  taskToStory,
+  syncPrdToTasks,
+  syncTasksToPrd,
+  importTasksToPrd,
+  bidirectionalSync,
+} from "./sync";