@towles/tool 0.0.52 → 0.0.54

package/README.md

@@ -1,14 +1,6 @@
 # Towles Tool
 
-Personal CLI toolkit with autonomous task runner and quality-of-life commands for daily development.
-
-## Features
-
-- **Ralph** - Autonomous task runner with session forking and context reuse
-- **Observability** - Token usage visualization with interactive treemaps
-- **Git workflows** - Branch creation, PR generation, and cleanup
-- **Journaling** - Daily notes, meeting notes, and general notes
-- **Claude Code plugins** - Personal plugin marketplace for Claude Code integration
+Personal CLI toolkit with autonomous task runner and developer utilities.
 
 ## Installation
 
@@ -26,93 +18,71 @@ claude plugin update tt@towles-tool
 git clone https://github.com/ChrisTowles/towles-tool.git
 cd towles-tool
 pnpm install
-pnpm start  # Run directly with tsx
+pnpm start
 ```
 
 ## CLI Commands
 
 ### Ralph (autonomous runner)
 
-| Command                     | Description                                   |
-| --------------------------- | --------------------------------------------- |
-| `tt ralph plan add <desc>`  | Add task to plan                              |
-| `tt ralph plan list`        | View tasks                                    |
-| `tt ralph plan done <id>`   | Mark task complete                            |
-| `tt ralph plan remove <id>` | Remove task                                   |
-| `tt ralph run`              | Run autonomous loop (auto-commits by default) |
-| `tt ralph show`             | Show plan with mermaid graph                  |
+| Command                       | Description            |
+| ----------------------------- | ---------------------- |
+| `tt ralph plan add "path.md"` | Add plan from file     |
+| `tt ralph plan list`          | View plans             |
+| `tt ralph plan done <id>`     | Mark complete          |
+| `tt ralph plan remove <id>`   | Remove plan            |
+| `tt ralph show`               | Show plan with mermaid |
+| `tt ralph run`                | Run (auto-commits)     |
+| `tt ralph run --planId 5`     | Run specific plan      |
 
 ### Observability
 
-| Command                   | Description                           |
-| ------------------------- | ------------------------------------- |
-| `tt graph`                | Generate HTML treemap of all sessions |
-| `tt graph --session <id>` | Single session treemap                |
-| `tt graph --open`         | Auto-open in browser                  |
-
-Treemap colors indicate input/output token ratio: green <2:1, yellow 2-5:1, red >5:1.
+| Command                   | Description              |
+| ------------------------- | ------------------------ |
+| `tt graph`                | Token Usage (auto-opens) |
+| `tt graph --session <id>` | Single session           |
+| `tt graph --days 14`      | Filter to last N days    |
 
 ### Git
 
-| Command              | Alias   | Description                     |
-| -------------------- | ------- | ------------------------------- |
-| `tt gh branch`       |         | Create branch from GitHub issue |
-| `tt gh pr`           | `tt pr` | Create pull request             |
-| `tt gh branch-clean` |         | Delete merged branches          |
+| Command              | Description                     |
+| -------------------- | ------------------------------- |
+| `tt gh branch`       | Create branch from GitHub issue |
+| `tt gh pr`           | Create pull request             |
+| `tt gh branch-clean` | Delete merged branches          |
 
 ### Journaling
 
-| Command                  | Alias      | Description                      |
-| ------------------------ | ---------- | -------------------------------- |
-| `tt journal daily-notes` | `tt today` | Weekly files with daily sections |
-| `tt journal meeting`     | `tt m`     | Meeting notes                    |
-| `tt journal note`        | `tt n`     | General notes                    |
+| Command                  | Alias      | Description   |
+| ------------------------ | ---------- | ------------- |
+| `tt journal daily-notes` | `tt today` | Weekly/daily  |
+| `tt journal meeting`     | `tt m`     | Meeting notes |
+| `tt journal note`        | `tt n`     | General notes |
 
 ### Utilities
 
-| Command      | Alias    | Description                    |
-| ------------ | -------- | ------------------------------ |
-| `tt config`  | `tt cfg` | Show configuration             |
-| `tt doctor`  |          | Check dependencies             |
-| `tt install` |          | Configure Claude Code settings |
-
-## Claude Code Plugin Skills
-
-Available via `/tt:<command>`:
-
-| Command       | Description                                   |
-| ------------- | --------------------------------------------- |
-| `/tt:commit`  | AI-powered conventional commit messages       |
-| `/tt:plan`    | Interview user and create implementation plan |
-| `/tt:improve` | Explore codebase and suggest improvements     |
-| `/tt:refine`  | Fix grammar/spelling in files                 |
-
-## Development
+| Command      | Description                    |
+| ------------ | ------------------------------ |
+| `tt config`  | Show configuration             |
+| `tt doctor`  | Check dependencies             |
+| `tt install` | Configure Claude Code settings |
 
-```bash
-pnpm start              # Run CLI with tsx
-pnpm test               # Run tests
-pnpm lint               # Run oxlint
-pnpm format             # Format with oxfmt
-pnpm typecheck          # Type check
-```
-
-### Releasing
-
-```bash
-gh workflow run release.yml -f bump_type=patch  # or minor/major
-gh run watch
-```
+## Claude Code Skills
 
-## Resources
+| Skill                    | Description                   |
+| ------------------------ | ----------------------------- |
+| `/tt:plan`               | Create implementation plan    |
+| `/tt:improve`            | Suggest codebase improvements |
+| `/tt:refactor-claude-md` | Fix grammar/spelling          |
+| `/tt:refine`             | Fix grammar/spelling          |
 
-### Claude Code Plugin Development
+## Guidelines
 
-- [Claude Code Plugins Announcement](https://www.anthropic.com/news/claude-code-plugins)
-- [Official Claude Code Plugins](https://github.com/anthropics/claude-code/tree/main/plugins)
-- [Skills Guide](https://docs.claude.com/en/api/skills-guide)
-- [Best Practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices)
+- [Architecture](docs/architecture.md) - CLI structure, plugin system, tech stack
+- [Claude Code Planning and Running Usage](docs/ralph-tools-for-claude-code.md) - "Claude Code" autonomous runner
+- [CICD via GitHub Actions](docs/github-actions.md) - Automated release workflow
+- [Testing](docs/testings.md) - Info about Tests
 
 ## License
 
-[MIT](./LICENSE) License © [Chris Towles](https://github.com/ChrisTowles)
+[MIT](./LICENSE) © [Chris Towles](https://github.com/ChrisTowles)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towles/tool",
-  "version": "0.0.52",
+  "version": "0.0.54",
   "description": "CLI tool with autonomous task runner (ralph), observability, and quality-of-life commands for daily development.",
   "keywords": [
     "autonomic",
@@ -79,15 +79,16 @@
     "vitest": "^3.1.3"
   },
   "simple-git-hooks": {
-    "pre-commit": "pnpm lint-staged && pnpm typecheck"
+    "pre-commit": "pnpm lint-staged && pnpm format && pnpm typecheck"
   },
   "lint-staged": {
     "package.json": "oxfmt --write",
     "*.{ts,tsx,mts,cts,js,cjs,mjs}": [
-      "oxfmt --write",
       "oxlint --fix"
     ],
-    "*.{json,md,yaml,yml}": "oxfmt --write"
+    "*.*": [
+      "oxfmt --write"
+    ]
   },
   "oclif": {
     "bin": "tt",

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;
 }