@towles/tool 0.0.59 → 0.0.60

package/src/lib/auto-claude/prompt-templates/05_implement.prompt.md

@@ -0,0 +1,36 @@
+You are an implementation agent. Follow the checklist in @{{ISSUE_DIR}}/plan-implementation.md task by task.
+
+The issue is in @{{ISSUE_DIR}}/initial-ramblings.md — background context only. Your ONLY source of truth is the checklist.
+
+The code lives primarily at `{{SCOPE_PATH}}/`.
+
+## How to work
+
+1. Find the next unchecked (`- [ ]`) task in order, top to bottom
+2. If the task includes tests, use **red/green TDD**:
+   - Write the test → run tests → confirm it **fails** (red)
+   - Implement the change → run tests → confirm it **passes** (green)
+3. If no tests, execute the task directly
+4. Update the checklist: `- [ ]` → `- [x]`
+5. Commit: `feat(scope): description` or `fix(scope): description`
+6. Repeat until all tasks are done
+
+Do NOT push to remote. Do NOT stop until all tasks are completed.
+
+## Mandatory verification
+
+Before writing completed-summary.md, run the project's type-check, test, and lint commands. Fix any errors and re-run until all pass.
+
+## When ALL checkboxes are `- [x]`
+
+Write @{{ISSUE_DIR}}/completed-summary.md — brief summary of everything implemented. Do NOT create it if ANY tasks remain unchecked.
+
+## Code quality
+
+- Follow the project's coding conventions from CLAUDE.md.
+- No unnecessary comments or jsdocs. Proper typing — no `any`.
+- Prefer real implementations over mocks — only mock at external boundaries (network, filesystem, third-party APIs).
+- Do not write tests for things the type system or compiler already enforces.
+- Follow the checklist literally. Do NOT skip tasks.
+- If something unexpected happens, document it on the task and proceed.
+- Fix bugs you encounter in the area you're working on. Reuse existing abstractions.

package/src/lib/auto-claude/prompt-templates/06_review.prompt.md

@@ -0,0 +1,32 @@
+You are reviewing code changes for the issue in @{{ISSUE_DIR}}/initial-ramblings.md. The plan is in @{{ISSUE_DIR}}/plan.md and checklist in @{{ISSUE_DIR}}/plan-implementation.md.
+
+## Automated checks
+
+Run the project's type-check, test, and lint commands first. Fix any failures before manual review.
+
+## Manual review
+
+Run `git diff {{MAIN_BRANCH}}...HEAD` and check:
+
+1. **Correctness** — does it implement what the plan describes?
+2. **Imports** — all present and correct?
+3. **Type errors** — any obvious issues?
+4. **Unused code** — variables, imports, or functions added but never used?
+5. **Pattern consistency** — follows existing codebase conventions?
+6. **Security** — any injection vulnerabilities or unsafe operations?
+7. **Edge cases** — anything that could break under unusual input?
+8. **Incomplete work** — TODOs, placeholders, unfinished implementations?
+9. **Test coverage** — new behaviors covered by tests? Existing tests updated?
+
+After review, run the code-simplify skill on changed files. Apply simplifications that improve clarity without changing behavior — commit separately.
+
+Fix issues directly, commit as `fix(scope): review fixes for issue #N`.
+
+## Write @{{ISSUE_DIR}}/review.md
+
+- **Status**: PASS, PASS WITH FIXES, or FAIL
+  - FAIL = fundamentally broken (wrong approach, missing core functionality, unfixable regressions). Explain what's wrong.
+- **Issues found** — what was wrong and what you fixed
+- **Confidence level** — high/medium/low
+- **Notes** — anything the PR reviewer should check
+- **Recommended follow-ups** — only if genuinely valuable. Omit if nothing worth flagging.

package/src/lib/auto-claude/prompt-templates/07_refresh.prompt.md

@@ -0,0 +1,30 @@
+You are updating an existing auto-claude branch to be compatible with the latest {{MAIN_BRANCH}}.
+
+## Context
+
+- Original issue: @{{ISSUE_DIR}}/initial-ramblings.md
+- Checklist: @{{ISSUE_DIR}}/plan-implementation.md
+- What was implemented: @{{ISSUE_DIR}}/completed-summary.md
+
+The code lives primarily at `{{SCOPE_PATH}}/`.
+
+## Your task
+
+1. `git diff {{MAIN_BRANCH}}...HEAD` — what this PR changes
+2. `git log {{MAIN_BRANCH}}..HEAD --oneline` — PR's commit history
+3. `git diff HEAD...{{MAIN_BRANCH}}` — what {{MAIN_BRANCH}} changed since divergence
+4. Check: do imports resolve? Do types/APIs still match? Conflicts with {{MAIN_BRANCH}}?
+5. Fix issues directly. For merge conflicts, preserve PR intent while adopting {{MAIN_BRANCH}}'s patterns. Commit: `fix(scope): adapt to {{MAIN_BRANCH}} changes`
+6. Run the project's type-check, test, and lint commands. Fix any errors.
+
+**CRITICAL:**
+
+- Do NOT re-implement. Only fix what broke due to {{MAIN_BRANCH}} changes.
+- If {{MAIN_BRANCH}} changed so fundamentally the PR's approach is no longer viable, report `NEEDS-ATTENTION`. Do NOT force a fix.
+- Do NOT push to remote. Do NOT modify plan or research files.
+
+## Write @{{ISSUE_DIR}}/refresh-summary.md
+
+- **Status**: UP-TO-DATE, ADAPTED, or NEEDS-ATTENTION
+- **Changes made** — what broke and how you fixed it
+- **Risk areas** — anything a reviewer should double-check

package/src/lib/auto-claude/prompt-templates/CLAUDE.md

@@ -0,0 +1,12 @@
+# Prompt Templates
+
+These templates are **language and toolchain agnostic**. They must not reference specific tools (pnpm, vitest, cargo, pytest, etc.), languages (TypeScript, Rust, Python), or framework conventions (oclif, Zod, consola).
+
+Project-specific details (test commands, lint commands, type-check commands, coding conventions) come from the **target repo's CLAUDE.md**, which Claude Code loads automatically at runtime.
+
+When editing templates:
+
+- Say "run the project's test/lint/type-check commands" — not `pnpm test` or `cargo test`
+- Say "test files" — not `*.test.ts` or `*_test.py`
+- Say "schema validation" — not "Zod schemas"
+- Say "follow the project's coding conventions from CLAUDE.md" — not "use consola" or "use import type"

package/src/lib/auto-claude/prompt-templates/index.test.ts

@@ -28,9 +28,9 @@ describe("TEMPLATES", () => {
     }
   });
 
-  it("filenames should follow XX-prompt-*.md pattern", () => {
+  it("filenames should follow NN_step.prompt.md pattern", () => {
     for (const filename of Object.values(TEMPLATES)) {
-      expect(filename).toMatch(/^\d{2}-prompt-.+\.md$/);
+      expect(filename).toMatch(/^\d{2}_.+\.prompt\.md$/);
     }
   });
 

package/src/lib/auto-claude/prompt-templates/index.ts

@@ -1,11 +1,11 @@
 export const TEMPLATES = {
-  research: "01-prompt-research.md",
-  plan: "02-prompt-plan.md",
-  planAnnotations: "03-prompt-plan-annotations.md",
-  planImplementation: "04-prompt-plan-implementation.md",
-  implement: "05-prompt-implement.md",
-  review: "06-prompt-review.md",
-  refresh: "07-prompt-refresh.md",
+  research: "01_research.prompt.md",
+  plan: "02_plan.prompt.md",
+  planAnnotations: "03_plan-annotations.prompt.md",
+  planImplementation: "04_plan-implementation.prompt.md",
+  implement: "05_implement.prompt.md",
+  review: "06_review.prompt.md",
+  refresh: "07_refresh.prompt.md",
 } as const;
 
 export const PIPELINE_STEPS = [

package/src/lib/auto-claude/run-claude.test.ts

@@ -0,0 +1,160 @@
+import consola from "consola";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { initConfig } from "./config";
+import { createTestRepo } from "./test-helpers";
+import type { TestRepo } from "./test-helpers";
+
+consola.level = -999;
+
+// ── File-level tinyexec mock -- intercepts all x() calls ──
+
+let mockXImpl: ((...args: unknown[]) => unknown) | null = null;
+
+vi.mock("tinyexec", () => ({
+  x: vi.fn((...args: unknown[]) => {
+    if (mockXImpl) return mockXImpl(...args);
+    throw new Error("mockXImpl not set");
+  }),
+}));
+
+describe("runClaude (mocked tinyexec)", () => {
+  let originalCwd: string;
+  let repo: TestRepo;
+
+  beforeAll(async () => {
+    originalCwd = process.cwd();
+    repo = createTestRepo();
+    process.chdir(repo.dir);
+  });
+
+  afterAll(() => {
+    process.chdir(originalCwd);
+    repo.cleanup();
+  });
+
+  beforeEach(() => {
+    mockXImpl = null;
+    vi.clearAllMocks();
+  });
+
+  it("constructs correct args and parses JSON result", async () => {
+    mockXImpl = vi.fn().mockResolvedValue({
+      stdout: JSON.stringify({
+        result: "All done",
+        is_error: false,
+        total_cost_usd: 0.05,
+        num_turns: 3,
+      }),
+      exitCode: 0,
+    });
+
+    await initConfig({ repo: "test/repo", mainBranch: "main" });
+
+    const { runClaude } = await import("./utils");
+
+    const result = await runClaude({
+      promptFile: "test-prompt.md",
+      permissionMode: "plan",
+      maxTurns: 10,
+    });
+
+    expect(result.result).toBe("All done");
+    expect(result.is_error).toBe(false);
+    expect(result.num_turns).toBe(3);
+
+    expect(mockXImpl).toHaveBeenCalledWith(
+      "claude",
+      expect.arrayContaining([
+        "-p",
+        "--output-format",
+        "json",
+        "--permission-mode",
+        "plan",
+        "--max-turns",
+        "10",
+        "@test-prompt.md",
+      ]),
+      expect.any(Object),
+    );
+  });
+
+  it("returns fallback when JSON parsing fails", async () => {
+    mockXImpl = vi.fn().mockResolvedValue({ stdout: "not json output", exitCode: 0 });
+
+    await initConfig({ repo: "test/repo", mainBranch: "main" });
+
+    const { runClaude } = await import("./utils");
+
+    const result = await runClaude({
+      promptFile: "test.md",
+      permissionMode: "acceptEdits",
+    });
+
+    expect(result.result).toBe("not json output");
+    expect(result.is_error).toBe(false);
+    expect(result.total_cost_usd).toBe(0);
+  });
+
+  it("retries on failure when retry is enabled", async () => {
+    let callCount = 0;
+    mockXImpl = vi.fn().mockImplementation(() => {
+      callCount++;
+      if (callCount < 3) {
+        throw new Error("Claude process failed");
+      }
+      return Promise.resolve({
+        stdout: JSON.stringify({
+          result: "ok",
+          is_error: false,
+          total_cost_usd: 0,
+          num_turns: 1,
+        }),
+        exitCode: 0,
+      });
+    });
+
+    await initConfig({
+      repo: "test/repo",
+      mainBranch: "main",
+      loopRetryEnabled: true,
+      maxRetries: 5,
+      retryDelayMs: 1,
+      maxRetryDelayMs: 5,
+    });
+
+    const { runClaude } = await import("./utils");
+
+    const result = await runClaude({
+      promptFile: "test.md",
+      permissionMode: "plan",
+      retry: true,
+    });
+
+    expect(result.result).toBe("ok");
+    expect(callCount).toBe(3);
+  }, 10_000);
+
+  it("throws after max retries exhausted", async () => {
+    mockXImpl = vi.fn().mockRejectedValue(new Error("Claude crash"));
+
+    await initConfig({
+      repo: "test/repo",
+      mainBranch: "main",
+      loopRetryEnabled: true,
+      maxRetries: 2,
+      retryDelayMs: 1,
+      maxRetryDelayMs: 5,
+    });
+
+    const { runClaude } = await import("./utils");
+
+    await expect(
+      runClaude({
+        promptFile: "test.md",
+        permissionMode: "plan",
+        retry: true,
+      }),
+    ).rejects.toThrow("Claude failed after 2 retries");
+  }, 10_000);
+});

package/src/lib/auto-claude/steps/steps.test.ts

@@ -0,0 +1,330 @@
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import consola from "consola";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { initConfig } from "../config";
+import { ARTIFACTS } from "../prompt-templates/index";
+import {
+  buildTestContext,
+  createTestRepoWithRemote,
+  errorClaudeJson,
+  successClaudeJson,
+} from "../test-helpers";
+import type { TestRepo } from "../test-helpers";
+import type { IssueContext } from "../utils";
+
+consola.level = -999;
+
+// ── Mock tinyexec: intercept "claude" calls, pass through everything else ──
+
+let mockClaudeImpl: ((args: string[]) => Promise<{ stdout: string; exitCode: number }>) | null =
+  null;
+
+vi.mock("tinyexec", async (importOriginal) => {
+  const original = await importOriginal<typeof import("tinyexec")>();
+  return {
+    ...original,
+    x: vi.fn(
+      async (
+        cmd: string,
+        args: string[],
+        opts?: Record<string, unknown>,
+      ): Promise<{ stdout: string; exitCode: number }> => {
+        if (cmd === "claude" && mockClaudeImpl) {
+          return mockClaudeImpl(args);
+        }
+        if (cmd === "claude") {
+          throw new Error("Unexpected claude call -- set mockClaudeImpl before running");
+        }
+        return original.x(cmd, args, opts as never) as unknown as Promise<{
+          stdout: string;
+          exitCode: number;
+        }>;
+      },
+    ),
+  };
+});
+
+// ── Shared setup/teardown for all step tests ──
+
+function setupStepTest(): { originalCwd: string; repo: TestRepo; ctx: IssueContext } {
+  const originalCwd = process.cwd();
+  const repo = createTestRepoWithRemote();
+  process.chdir(repo.dir);
+  const ctx = buildTestContext(repo.dir);
+  mkdirSync(ctx.issueDir, { recursive: true });
+  mockClaudeImpl = null;
+  return { originalCwd, repo, ctx };
+}
+
+function teardownStepTest(originalCwd: string, repo: TestRepo): void {
+  process.chdir(originalCwd);
+  repo.cleanup();
+}
+
+// ── runStepWithArtifact ──
+
+describe("runStepWithArtifact", () => {
+  let originalCwd: string;
+  let repo: TestRepo;
+  let ctx: IssueContext;
+
+  beforeEach(async () => {
+    ({ originalCwd, repo, ctx } = setupStepTest());
+    await initConfig({ repo: "test/repo", mainBranch: "main" });
+  });
+
+  afterEach(() => teardownStepTest(originalCwd, repo));
+
+  it("skips when artifact already exists", async () => {
+    const { runStepWithArtifact } = await import("../utils");
+    const artifactPath = join(ctx.issueDir, "test-artifact.md");
+    writeFileSync(artifactPath, "# Existing artifact content");
+
+    const result = await runStepWithArtifact({
+      stepName: "Test Step",
+      ctx,
+      artifactPath,
+      templateName: "01_research.prompt.md",
+    });
+
+    expect(result).toBe(true);
+  });
+
+  it("returns false when Claude returns is_error", async () => {
+    mockClaudeImpl = async () => ({ stdout: errorClaudeJson(), exitCode: 0 });
+
+    const { runStepWithArtifact } = await import("../utils");
+    const artifactPath = join(ctx.issueDir, "missing-artifact.md");
+
+    const result = await runStepWithArtifact({
+      stepName: "Test Step",
+      ctx,
+      artifactPath,
+      templateName: "01_research.prompt.md",
+    });
+
+    expect(result).toBe(false);
+  });
+
+  it("returns false when artifact not produced after Claude run", async () => {
+    mockClaudeImpl = async () => ({ stdout: successClaudeJson(), exitCode: 0 });
+
+    const { runStepWithArtifact } = await import("../utils");
+    const artifactPath = join(ctx.issueDir, "never-created.md");
+
+    const result = await runStepWithArtifact({
+      stepName: "Test Step",
+      ctx,
+      artifactPath,
+      templateName: "01_research.prompt.md",
+    });
+
+    expect(result).toBe(false);
+  });
+
+  it("succeeds and commits when Claude produces artifact", async () => {
+    const { runStepWithArtifact } = await import("../utils");
+    const artifactPath = join(ctx.issueDir, "plan.md");
+
+    mockClaudeImpl = async () => {
+      writeFileSync(artifactPath, "# Plan\n\nDetailed plan content here.");
+      return { stdout: successClaudeJson(), exitCode: 0 };
+    };
+
+    const result = await runStepWithArtifact({
+      stepName: "Test Step",
+      ctx,
+      artifactPath,
+      templateName: "01_research.prompt.md",
+    });
+
+    expect(result).toBe(true);
+
+    const log = execSync("git log --oneline", { cwd: repo.dir, encoding: "utf-8" });
+    expect(log).toContain("chore(auto-claude)");
+  });
+});
+
+// ── stepResearch ──
+
+describe("stepResearch", () => {
+  let originalCwd: string;
+  let repo: TestRepo;
+  let ctx: IssueContext;
+
+  beforeEach(async () => {
+    ({ originalCwd, repo, ctx } = setupStepTest());
+    await initConfig({ repo: "test/repo", mainBranch: "main" });
+  });
+
+  afterEach(() => teardownStepTest(originalCwd, repo));
+
+  it("skips when research.md exists and is > 200 chars", async () => {
+    const { stepResearch } = await import("./research");
+
+    writeFileSync(join(ctx.issueDir, ARTIFACTS.research), "x".repeat(250));
+
+    const result = await stepResearch(ctx);
+    expect(result).toBe(true);
+  });
+
+  it("does NOT skip when research.md exists but is < 200 chars", async () => {
+    const { stepResearch } = await import("./research");
+
+    const researchPath = join(ctx.issueDir, ARTIFACTS.research);
+    writeFileSync(researchPath, "short");
+
+    let claudeCalled = false;
+    mockClaudeImpl = async () => {
+      claudeCalled = true;
+      writeFileSync(researchPath, "x".repeat(250));
+      return { stdout: successClaudeJson(), exitCode: 0 };
+    };
+
+    const result = await stepResearch(ctx);
+    expect(claudeCalled).toBe(true);
+    expect(result).toBe(true);
+  });
+
+  it("calls ensureBranch (real git branch creation)", async () => {
+    const { stepResearch } = await import("./research");
+
+    const researchPath = join(ctx.issueDir, ARTIFACTS.research);
+    mockClaudeImpl = async () => {
+      writeFileSync(researchPath, "x".repeat(250));
+      return { stdout: successClaudeJson(), exitCode: 0 };
+    };
+
+    await stepResearch(ctx);
+
+    const branches = execSync("git branch", { cwd: repo.dir, encoding: "utf-8" });
+    expect(branches).toContain(ctx.branch.split("/").pop());
+  });
+});
+
+// ── stepPlanAnnotations ──
+
+describe("stepPlanAnnotations", () => {
+  let originalCwd: string;
+  let repo: TestRepo;
+  let ctx: IssueContext;
+
+  beforeEach(async () => {
+    ({ originalCwd, repo, ctx } = setupStepTest());
+    await initConfig({ repo: "test/repo", mainBranch: "main" });
+  });
+
+  afterEach(() => teardownStepTest(originalCwd, repo));
+
+  it("returns true when no plan-annotations.md exists", async () => {
+    const { stepPlanAnnotations } = await import("./plan-annotations");
+
+    const result = await stepPlanAnnotations(ctx);
+    expect(result).toBe(true);
+  });
+
+  it("skips when plan-annotations-addressed.md already exists", async () => {
+    const { stepPlanAnnotations } = await import("./plan-annotations");
+
+    writeFileSync(join(ctx.issueDir, ARTIFACTS.planAnnotations), "# Annotations");
+    writeFileSync(join(ctx.issueDir, ARTIFACTS.planAnnotationsAddressed), "# Addressed");
+
+    const result = await stepPlanAnnotations(ctx);
+    expect(result).toBe(true);
+  });
+
+  it("renames file after Claude runs successfully", async () => {
+    const { stepPlanAnnotations } = await import("./plan-annotations");
+
+    const annotationsPath = join(ctx.issueDir, ARTIFACTS.planAnnotations);
+    const addressedPath = join(ctx.issueDir, ARTIFACTS.planAnnotationsAddressed);
+    writeFileSync(annotationsPath, "# Annotations\n\nSome feedback here.");
+
+    mockClaudeImpl = async () => ({ stdout: successClaudeJson(), exitCode: 0 });
+
+    const result = await stepPlanAnnotations(ctx);
+
+    expect(result).toBe(true);
+    expect(existsSync(addressedPath)).toBe(true);
+    expect(existsSync(annotationsPath)).toBe(false);
+  });
+});
+
+// ── stepImplement ──
+
+describe("stepImplement", () => {
+  let originalCwd: string;
+  let repo: TestRepo;
+  let ctx: IssueContext;
+
+  beforeEach(async () => {
+    ({ originalCwd, repo, ctx } = setupStepTest());
+    await initConfig({
+      repo: "test/repo",
+      mainBranch: "main",
+      maxImplementIterations: 3,
+    });
+
+    // stepImplement does `git checkout ctx.branch`, so create the branch
+    execSync(`git checkout -b ${ctx.branch}`, { cwd: repo.dir, stdio: "ignore" });
+  });
+
+  afterEach(() => teardownStepTest(originalCwd, repo));
+
+  it("skips when completed-summary.md exists", async () => {
+    const { stepImplement } = await import("./implement");
+
+    writeFileSync(join(ctx.issueDir, ARTIFACTS.completedSummary), "# Done");
+
+    const result = await stepImplement(ctx);
+    expect(result).toBe(true);
+  });
+
+  it("returns false after maxImplementIterations exhausted", async () => {
+    const { stepImplement } = await import("./implement");
+
+    let callCount = 0;
+    mockClaudeImpl = async () => {
+      callCount++;
+      return { stdout: successClaudeJson(), exitCode: 0 };
+    };
+
+    const result = await stepImplement(ctx);
+    expect(result).toBe(false);
+    expect(callCount).toBe(3);
+  });
+
+  it("stops looping when completed-summary.md appears", async () => {
+    const { stepImplement } = await import("./implement");
+
+    let callCount = 0;
+    const completedPath = join(ctx.issueDir, ARTIFACTS.completedSummary);
+
+    mockClaudeImpl = async () => {
+      callCount++;
+      if (callCount === 2) {
+        writeFileSync(completedPath, "# Implementation Complete\n\nAll tasks done.");
+      }
+      return { stdout: successClaudeJson(), exitCode: 0 };
+    };
+
+    const result = await stepImplement(ctx);
+    expect(result).toBe(true);
+    expect(callCount).toBe(2);
+  });
+});
+
+// ── stepCreatePR / stepRemoveLabel -- skip in CI (needs gh) ──
+
+describe.skipIf(!!process.env.CI)("stepCreatePR (requires gh)", () => {
+  it.todo("skips when open PR already exists");
+  it.todo("creates PR and writes pr-url.txt");
+});
+
+describe.skipIf(!!process.env.CI)("stepRemoveLabel (requires gh)", () => {
+  it.todo("calls gh with correct args");
+});