@towles/tool 0.0.52 → 0.0.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towles/tool",
-  "version": "0.0.52",
+  "version": "0.0.53",
   "description": "CLI tool with autonomous task runner (ralph), observability, and quality-of-life commands for daily development.",
   "keywords": [
     "autonomic",

package/src/commands/ralph/plan/add.ts

@@ -1,6 +1,6 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
-import { Flags } from "@oclif/core";
+import { Args, Flags } from "@oclif/core";
 import consola from "consola";
 import { colors } from "consola/utils";
 import { BaseCommand } from "../../base.js";
@@ -22,17 +22,19 @@ export default class PlanAdd extends BaseCommand {
   static override examples = [
     {
       description: "Add a plan from a markdown file",
-      command: "<%= config.bin %> <%= command.id %> --file docs/plans/2025-01-18-feature.md",
+      command: "<%= config.bin %> <%= command.id %> docs/plans/2025-01-18-feature.md",
     },
   ];
 
-  static override flags = {
-    ...BaseCommand.baseFlags,
-    file: Flags.string({
-      char: "f",
+  static override args = {
+    file: Args.string({
       description: "Path to plan file (markdown)",
       required: true,
     }),
+  };
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
     stateFile: Flags.string({
       char: "s",
       description: `State file path (default: ${DEFAULT_STATE_FILE})`,
@@ -40,11 +42,11 @@ export default class PlanAdd extends BaseCommand {
   };
 
   async run(): Promise<void> {
-    const { flags } = await this.parse(PlanAdd);
+    const { args, flags } = await this.parse(PlanAdd);
     const ralphSettings = this.settings.settings.ralphSettings;
     const stateFile = resolveRalphPath(flags.stateFile, "stateFile", ralphSettings);
 
-    const planFilePath = resolve(flags.file);
+    const planFilePath = resolve(args.file);
 
     if (!existsSync(planFilePath)) {
       this.error(`Plan file not found: ${planFilePath}`);

package/src/commands/ralph/run.test.ts

@@ -22,6 +22,7 @@ import {
   DEFAULT_STATE_FILE,
   DEFAULT_HISTORY_FILE,
   DEFAULT_COMPLETION_MARKER,
+  DEFAULT_TASK_DONE_MARKER,
   CLAUDE_DEFAULT_ARGS,
 } from "../../lib/ralph/index.js";
 
@@ -45,6 +46,7 @@ describe("ralph-loop", () => {
       expect(DEFAULT_STATE_FILE).toBe("./.claude/.ralph/ralph-state.local.json");
       expect(DEFAULT_HISTORY_FILE).toBe("./.claude/.ralph/ralph-history.local.log");
       expect(DEFAULT_COMPLETION_MARKER).toBe("RALPH_DONE");
+      expect(DEFAULT_TASK_DONE_MARKER).toBe("TASK_DONE");
       expect(CLAUDE_DEFAULT_ARGS).toEqual([
         "--print",
         "--verbose",
@@ -99,43 +101,81 @@ describe("ralph-loop", () => {
       status: "ready",
       addedAt: new Date().toISOString(),
     };
-    const testPlanContent = "First plan content";
 
     it("should include completion marker", () => {
       const prompt = buildIterationPrompt({
         completionMarker: "RALPH_DONE",
+        taskDoneMarker: "TASK_DONE",
         plan: testPlan,
-        planContent: testPlanContent,
       });
       expect(prompt).toContain("RALPH_DONE");
     });
 
-    it("should include plan content", () => {
+    it("should include plan file path for reading", () => {
       const prompt = buildIterationPrompt({
         completionMarker: "RALPH_DONE",
+        taskDoneMarker: "TASK_DONE",
         plan: testPlan,
-        planContent: testPlanContent,
       });
-      expect(prompt).toContain("First plan content");
+      expect(prompt).toContain("/tmp/first-plan.md");
+      expect(prompt).toContain("Read Plan:");
     });
 
-    it("should include mark done command with plan id", () => {
+    it("should include instruction to update plan file", () => {
       const prompt = buildIterationPrompt({
         completionMarker: "RALPH_DONE",
+        taskDoneMarker: "TASK_DONE",
         plan: testPlan,
-        planContent: testPlanContent,
       });
-      expect(prompt).toContain("tt ralph plan done 1");
+      expect(prompt).toContain("Update the plan");
+      expect(prompt).toContain("/tmp/first-plan.md");
     });
 
     it("should include custom completion marker", () => {
       const prompt = buildIterationPrompt({
         completionMarker: "CUSTOM_MARKER",
+        taskDoneMarker: "TASK_DONE",
         plan: testPlan,
-        planContent: testPlanContent,
       });
       expect(prompt).toContain("CUSTOM_MARKER");
     });
+
+    it("should include TASK_DONE for tasks remaining", () => {
+      const prompt = buildIterationPrompt({
+        completionMarker: "RALPH_DONE",
+        taskDoneMarker: "TASK_DONE",
+        plan: testPlan,
+      });
+      expect(prompt).toContain("TASK_DONE");
+      expect(prompt).toContain("tasks remain");
+    });
+
+    it("should include RALPH_DONE for plan complete", () => {
+      const prompt = buildIterationPrompt({
+        completionMarker: "RALPH_DONE",
+        taskDoneMarker: "TASK_DONE",
+        plan: testPlan,
+      });
+      expect(prompt).toContain("RALPH_DONE");
+      expect(prompt).toContain("plan is complete");
+    });
+
+    it("should skip commit step when skipCommit is true", () => {
+      const promptWithCommit = buildIterationPrompt({
+        completionMarker: "RALPH_DONE",
+        taskDoneMarker: "TASK_DONE",
+        plan: testPlan,
+        skipCommit: false,
+      });
+      const promptWithoutCommit = buildIterationPrompt({
+        completionMarker: "RALPH_DONE",
+        taskDoneMarker: "TASK_DONE",
+        plan: testPlan,
+        skipCommit: true,
+      });
+      expect(promptWithCommit).toContain("git commit");
+      expect(promptWithoutCommit).not.toContain("git commit");
+    });
   });
 
   describe("extractOutputSummary", () => {
@@ -200,6 +240,18 @@ describe("ralph-loop", () => {
     it("should be case-sensitive", () => {
       expect(detectCompletionMarker("ralph_done", "RALPH_DONE")).toBe(false);
     });
+
+    it("should detect TASK_DONE marker", () => {
+      expect(detectCompletionMarker("finished <promise>TASK_DONE</promise>", "TASK_DONE")).toBe(
+        true,
+      );
+    });
+
+    it("should distinguish TASK_DONE from RALPH_DONE", () => {
+      const output = "<promise>TASK_DONE</promise>";
+      expect(detectCompletionMarker(output, "TASK_DONE")).toBe(true);
+      expect(detectCompletionMarker(output, "RALPH_DONE")).toBe(false);
+    });
   });
 
   describe("state transitions", () => {
@@ -275,6 +327,26 @@ describe("ralph-loop", () => {
       expect(parsed2.outputSummary).toBe("second");
       expect(parsed2.markerFound).toBe(true);
     });
+
+    it("should include taskMarkerFound field", () => {
+      const history: IterationHistory = {
+        iteration: 1,
+        startedAt: "2026-01-19T10:00:00Z",
+        completedAt: "2026-01-19T10:01:00Z",
+        durationMs: 60000,
+        durationHuman: "1m 0s",
+        outputSummary: "test output",
+        markerFound: false,
+        taskMarkerFound: true,
+      };
+
+      appendHistory(history, testHistoryFile);
+
+      const content = require("node:fs").readFileSync(testHistoryFile, "utf-8");
+      const parsed = JSON.parse(content.trim());
+      expect(parsed.taskMarkerFound).toBe(true);
+      expect(parsed.markerFound).toBe(false);
+    });
   });
 
   describe("addPlanToState", () => {

package/src/commands/ralph/run.ts

@@ -8,13 +8,13 @@ import {
   DEFAULT_LOG_FILE,
   DEFAULT_MAX_ITERATIONS,
   DEFAULT_COMPLETION_MARKER,
+  DEFAULT_TASK_DONE_MARKER,
   CLAUDE_DEFAULT_ARGS,
   loadState,
   saveState,
   appendHistory,
   resolveRalphPath,
   getRalphPaths,
-  readPlanContent,
 } from "../../lib/ralph/state.js";
 import {
   buildIterationPrompt,
@@ -94,6 +94,10 @@ export default class Run extends BaseCommand {
       description: "Completion marker",
       default: DEFAULT_COMPLETION_MARKER,
     }),
+    taskDoneMarker: Flags.string({
+      description: "Task done marker",
+      default: DEFAULT_TASK_DONE_MARKER,
+    }),
   };
 
   async run(): Promise<void> {
@@ -147,6 +151,7 @@ export default class Run extends BaseCommand {
       consola.log(`  State file: ${stateFile}`);
       consola.log(`  Log file: ${logFile}`);
       consola.log(`  Completion marker: ${flags.completionMarker}`);
+      consola.log(`  Task done marker: ${flags.taskDoneMarker}`);
       consola.log(`  Auto-commit: ${flags.autoCommit}`);
       consola.log(`  Claude args: ${[...CLAUDE_DEFAULT_ARGS, ...extraClaudeArgs].join(" ")}`);
       consola.log(`  Remaining plans: ${remainingPlans.length}`);
@@ -154,17 +159,11 @@ export default class Run extends BaseCommand {
       consola.log(colors.cyan("\nCurrent plan:"));
       consola.log(`  #${currentPlan.id}: ${currentPlan.planFilePath}`);
 
-      // Read plan content
-      const planContent = readPlanContent(currentPlan, state, stateFile);
-      if (!planContent) {
-        this.error(`Cannot read plan file: ${currentPlan.planFilePath}`);
-      }
-
       // Show prompt preview
       const prompt = buildIterationPrompt({
         completionMarker: flags.completionMarker,
+        taskDoneMarker: flags.taskDoneMarker,
         plan: currentPlan,
-        planContent,
         skipCommit: !flags.autoCommit,
       });
       consola.log(colors.dim("─".repeat(60)));
@@ -248,18 +247,10 @@ export default class Run extends BaseCommand {
         break;
       }
 
-      // Read plan content
-      const planContent = readPlanContent(plan, state, stateFile);
-      if (!planContent) {
-        consola.log(colors.yellow(`⚠ Skipping plan #${plan.id}: cannot read file`));
-        logStream.write(`⚠ Skipping plan #${plan.id}: cannot read file\n`);
-        continue;
-      }
-
       const prompt = buildIterationPrompt({
         completionMarker: flags.completionMarker,
+        taskDoneMarker: flags.taskDoneMarker,
         plan: plan,
-        planContent,
         skipCommit: !flags.autoCommit,
       });
 
@@ -288,7 +279,8 @@ export default class Run extends BaseCommand {
       }
 
       const iterationEnd = new Date().toISOString();
-      const markerFound = detectCompletionMarker(iterResult.output, flags.completionMarker);
+      const taskMarkerFound = detectCompletionMarker(iterResult.output, flags.taskDoneMarker);
+      const planMarkerFound = detectCompletionMarker(iterResult.output, flags.completionMarker);
 
       // Calculate duration
       const startTime = new Date(iterationStart).getTime();
@@ -305,7 +297,8 @@ export default class Run extends BaseCommand {
           durationMs,
           durationHuman,
           outputSummary: extractOutputSummary(iterResult.output),
-          markerFound,
+          markerFound: planMarkerFound,
+          taskMarkerFound,
           contextUsedPercent: iterResult.contextUsedPercent,
         },
         ralphPaths.historyFile,
@@ -314,29 +307,35 @@ export default class Run extends BaseCommand {
       // Save state
       saveState(state, stateFile);
 
+      // Log marker status
+      if (taskMarkerFound) {
+        consola.log(colors.cyan(`Task marker found - current plan done, checking for more plans`));
+        logStream.write(`Task marker found - continuing to next plan\n`);
+      }
+
       // Log summary
       const contextInfo =
         iterResult.contextUsedPercent !== undefined
           ? ` | Context: ${iterResult.contextUsedPercent}%`
           : "";
       logStream.write(
-        `\n━━━ Iteration ${iteration} Summary ━━━\nDuration: ${durationHuman}${contextInfo}\nMarker found: ${markerFound ? "yes" : "no"}\n`,
+        `\n━━━ Iteration ${iteration} Summary ━━━\nDuration: ${durationHuman}${contextInfo}\nTask marker: ${taskMarkerFound ? "yes" : "no"}\nPlan marker: ${planMarkerFound ? "yes" : "no"}\n`,
       );
       consola.log(
         colors.dim(
-          `Duration: ${durationHuman}${contextInfo} | Marker: ${markerFound ? colors.green("yes") : colors.yellow("no")}`,
+          `Duration: ${durationHuman}${contextInfo} | Task: ${taskMarkerFound ? colors.green("yes") : colors.yellow("no")} | Plan: ${planMarkerFound ? colors.green("yes") : colors.yellow("no")}`,
         ),
       );
 
-      // Check completion
-      if (markerFound) {
+      // Check completion (only when ALL plans done marker found)
+      if (planMarkerFound) {
         completed = true;
         state.status = "completed";
         saveState(state, stateFile);
         consola.log(
-          colors.bold(colors.green(`\n✅ Plan completed after ${iteration} iteration(s)`)),
+          colors.bold(colors.green(`\n✅ All plans completed after ${iteration} iteration(s)`)),
         );
-        logStream.write(`\n✅ Plan completed after ${iteration} iteration(s)\n`);
+        logStream.write(`\n✅ All plans completed after ${iteration} iteration(s)\n`);
       }
     }
 

package/src/lib/ralph/formatter.ts

@@ -204,32 +204,28 @@ export function extractOutputSummary(output: string, maxLength: number = 2000):
 
 export interface BuildPromptOptions {
   completionMarker: string;
+  taskDoneMarker: string;
   plan: RalphPlan;
-  planContent: string;
   skipCommit?: boolean;
 }
 
 export function buildIterationPrompt({
   completionMarker,
+  taskDoneMarker,
   plan,
-  planContent,
   skipCommit = false,
 }: BuildPromptOptions): string {
   let step = 1;
 
   const prompt = `
-<plan>
-${planContent}
-</plan>
-
-<instructions>
-${step++}. Work on the plan above.
-${step++}. Run type checks and tests.
-${step++}. Mark done: \`tt ralph plan done ${plan.id}\`
+  <instructions>
+${step++}. Read Plan: \`${plan.planFilePath}\`
+${step++}. Choose next best task to work on.
+${step++}. Complete that task.
+${step++}. Update the plan \`${plan.planFilePath}\` to mark that task Done with any notes.
 ${skipCommit ? "" : `${step++}. Make a git commit.`}
+${step++}. If any tasks remain return <promise>${taskDoneMarker}</promise> else if plan is complete return <promise>${completionMarker}</promise>.
 
-**Before ending:** Run \`tt ralph plan list\` to check remaining plans.
-**ONLY if ALL PLANS are done** then Output: <promise>${completionMarker}</promise>
 </instructions>
 `;
   return prompt.trim();

package/src/lib/ralph/state.ts

@@ -12,6 +12,7 @@ import { RalphSettingsSchema } from "../../config/settings.js";
 export const DEFAULT_MAX_ITERATIONS = 10;
 export const DEFAULT_STATE_DIR = "./.claude/.ralph";
 export const DEFAULT_COMPLETION_MARKER = "RALPH_DONE";
+export const DEFAULT_TASK_DONE_MARKER = "TASK_DONE";
 
 // File names within stateDir
 const STATE_FILE_NAME = "ralph-state.local.json";
@@ -93,6 +94,7 @@ export interface IterationHistory {
   durationHuman: string;
   outputSummary: string;
   markerFound: boolean;
+  taskMarkerFound?: boolean;
   contextUsedPercent?: number;
 }