@towles/tool 0.0.59 → 0.0.61

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

@@ -0,0 +1,139 @@
+import type { ChildProcess } from "node:child_process";
+import { execSync } from "node:child_process";
+import { EventEmitter } from "node:events";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { PassThrough } from "node:stream";
+
+import { vi } from "vitest";
+
+import type { ClaudeResult, IssueContext } from "./utils";
+
+export interface TestRepo {
+  dir: string;
+  cleanup: () => void;
+}
+
+/**
+ * Creates a local git repo with a single empty commit on `main`.
+ */
+export function createTestRepo(prefix = "ac-test-"): TestRepo {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  execSync("git init", { cwd: dir, stdio: "ignore" });
+  execSync("git config user.email 'test@test.com'", { cwd: dir, stdio: "ignore" });
+  execSync("git config user.name 'Test'", { cwd: dir, stdio: "ignore" });
+  execSync("git commit --allow-empty -m 'init'", { cwd: dir, stdio: "ignore" });
+  execSync("git branch -M main", { cwd: dir, stdio: "ignore" });
+  return { dir, cleanup: () => rmSync(dir, { recursive: true, force: true }) };
+}
+
+/**
+ * Creates a local git repo backed by a bare clone acting as `origin`.
+ */
+export function createTestRepoWithRemote(prefix = "ac-test-remote-"): TestRepo {
+  const base = mkdtempSync(join(tmpdir(), prefix));
+  const workDir = join(base, "work");
+  const bareDir = join(base, "bare.git");
+
+  mkdirSync(workDir);
+  execSync("git init", { cwd: workDir, stdio: "ignore" });
+  execSync("git config user.email 'test@test.com'", { cwd: workDir, stdio: "ignore" });
+  execSync("git config user.name 'Test'", { cwd: workDir, stdio: "ignore" });
+  execSync("git commit --allow-empty -m 'init'", { cwd: workDir, stdio: "ignore" });
+  execSync("git branch -M main", { cwd: workDir, stdio: "ignore" });
+  execSync(`git clone --bare "${workDir}" "${bareDir}"`, { stdio: "ignore" });
+  execSync(`git remote add origin "${bareDir}"`, { cwd: workDir, stdio: "ignore" });
+  execSync("git push -u origin main", { cwd: workDir, stdio: "ignore" });
+
+  return { dir: workDir, cleanup: () => rmSync(base, { recursive: true, force: true }) };
+}
+
+/**
+ * Builds a minimal IssueContext for testing.
+ */
+export function buildTestContext(dir: string, issueNumber = 1): IssueContext {
+  const issueDirRel = `.auto-claude/issue-${issueNumber}`;
+  return {
+    number: issueNumber,
+    title: "Test Issue",
+    body: "Test body",
+    repo: "test/repo",
+    scopePath: ".",
+    issueDir: join(dir, issueDirRel),
+    issueDirRel,
+    branch: `feature/${issueNumber}-test-issue`,
+  };
+}
+
+/**
+ * Returns a stream-json result line for a successful ClaudeResult.
+ */
+export function successClaudeJson(result = "done"): string {
+  return JSON.stringify({
+    result,
+    is_error: false,
+    total_cost_usd: 0.01,
+    num_turns: 2,
+  } satisfies ClaudeResult);
+}
+
+/**
+ * Returns a stream-json result line for a failed ClaudeResult.
+ */
+export function errorClaudeJson(result = "failed"): string {
+  return JSON.stringify({
+    result,
+    is_error: true,
+    total_cost_usd: 0,
+    num_turns: 0,
+  } satisfies ClaudeResult);
+}
+
+/**
+ * Creates a fake ChildProcess with PassThrough stdout for testing
+ * the streaming runClaude implementation.
+ *
+ * Writes `stdout` content to the stream, then emits `close` with `exitCode`.
+ */
+export function createMockClaudeProcess(stdout: string, exitCode = 0): ChildProcess {
+  const proc = new EventEmitter() as ChildProcess;
+  const stdoutStream = new PassThrough();
+  (proc as unknown as { stdout: PassThrough }).stdout = stdoutStream;
+  (proc as unknown as { stderr: null }).stderr = null;
+  (proc as unknown as { stdin: null }).stdin = null;
+
+  // Write and close asynchronously so listeners can attach first
+  queueMicrotask(() => {
+    if (stdout) {
+      stdoutStream.write(`${stdout}\n`);
+    }
+    stdoutStream.end();
+    proc.emit("close", exitCode);
+  });
+
+  return proc;
+}
+
+export type MockClaudeImpl = ((args: string[]) => { stdout: string; exitCode: number }) | null;
+
+/**
+ * Creates the mock object for vi.mock("./spawn-claude").
+ * Must be called inside the vi.mock factory arrow (lazy) to avoid hoisting issues.
+ *
+ * Usage:
+ *   let mockClaudeImpl: MockClaudeImpl = null;
+ *   vi.mock("./spawn-claude", () => createSpawnClaudeMock(() => mockClaudeImpl));
+ */
+export function createSpawnClaudeMock(getImpl: () => MockClaudeImpl) {
+  return {
+    spawnClaude: vi.fn((args: string[]) => {
+      const impl = getImpl();
+      if (impl) {
+        const { stdout, exitCode } = impl(args);
+        return createMockClaudeProcess(stdout, exitCode);
+      }
+      throw new Error("Unexpected spawnClaude call -- set mockClaudeImpl");
+    }),
+  };
+}

package/src/lib/auto-claude/utils-execution.test.ts

@@ -0,0 +1,152 @@
+import { execSync } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import consola from "consola";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it } from "vitest";
+
+import { initConfig } from "./config";
+import { createTestRepo, createTestRepoWithRemote } from "./test-helpers";
+import type { TestRepo } from "./test-helpers";
+
+consola.level = -999;
+
+// ── Shell helpers: execSafe, git ──
+
+describe("shell helpers (real execution)", () => {
+  let originalCwd: string;
+  let repo: TestRepo;
+
+  beforeAll(async () => {
+    originalCwd = process.cwd();
+    repo = createTestRepo();
+    process.chdir(repo.dir);
+    await initConfig({ repo: "test/repo", mainBranch: "main" });
+  });
+
+  afterAll(() => {
+    process.chdir(originalCwd);
+    repo.cleanup();
+  });
+
+  it("execSafe returns ok:true for a successful command", async () => {
+    const { execSafe } = await import("./utils");
+    const result = await execSafe("echo", ["hello"]);
+    expect(result.ok).toBe(true);
+    expect(result.stdout).toBe("hello");
+  });
+
+  it("execSafe returns ok:false for a failing command", async () => {
+    const { execSafe } = await import("./utils");
+    const result = await execSafe("git", ["checkout", "nonexistent-branch-xyz"]);
+    expect(result.ok).toBe(false);
+  });
+
+  it("git() runs real git commands", async () => {
+    const { git } = await import("./utils");
+    const status = await git(["status", "--porcelain"]);
+    expect(typeof status).toBe("string");
+  });
+});
+
+// ── ensureBranch: real git with remote ──
+
+describe("ensureBranch (real git)", () => {
+  let originalCwd: string;
+  let repo: TestRepo;
+
+  beforeEach(async () => {
+    originalCwd = process.cwd();
+    repo = createTestRepoWithRemote();
+    process.chdir(repo.dir);
+    await initConfig({ repo: "test/repo", mainBranch: "main", remote: "origin" });
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    repo.cleanup();
+  });
+
+  it("creates a new branch from main when branch doesn't exist", async () => {
+    const { ensureBranch, git } = await import("./utils");
+
+    await ensureBranch("feature/42-new-branch");
+
+    const currentBranch = await git(["branch", "--show-current"]);
+    expect(currentBranch).toBe("feature/42-new-branch");
+  });
+
+  it("checks out an existing local branch", async () => {
+    const { ensureBranch, git } = await import("./utils");
+
+    execSync("git checkout -b feature/existing-branch", { cwd: repo.dir, stdio: "ignore" });
+    execSync("git checkout main", { cwd: repo.dir, stdio: "ignore" });
+
+    await ensureBranch("feature/existing-branch");
+
+    const currentBranch = await git(["branch", "--show-current"]);
+    expect(currentBranch).toBe("feature/existing-branch");
+  });
+
+  it("can checkout after branch creation", async () => {
+    const { ensureBranch, git } = await import("./utils");
+
+    await ensureBranch("feature/99-test-checkout");
+    const branch1 = await git(["branch", "--show-current"]);
+    expect(branch1).toBe("feature/99-test-checkout");
+
+    execSync("git checkout main", { cwd: repo.dir, stdio: "ignore" });
+    await ensureBranch("feature/99-test-checkout");
+    const branch2 = await git(["branch", "--show-current"]);
+    expect(branch2).toBe("feature/99-test-checkout");
+  });
+});
+
+// ── commitArtifacts: real git ──
+
+describe("commitArtifacts (real git)", () => {
+  let originalCwd: string;
+  let repo: TestRepo;
+
+  beforeEach(async () => {
+    originalCwd = process.cwd();
+    repo = createTestRepo();
+    process.chdir(repo.dir);
+    await initConfig({ repo: "test/repo", mainBranch: "main" });
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    repo.cleanup();
+  });
+
+  it("commits staged files in the issue directory", async () => {
+    const { commitArtifacts, buildIssueContext } = await import("./utils");
+
+    const ctx = buildIssueContext({ number: 1, title: "Test", body: "body" }, "test/repo", ".");
+
+    const issueDir = join(repo.dir, ctx.issueDirRel);
+    mkdirSync(issueDir, { recursive: true });
+    writeFileSync(join(issueDir, "test.md"), "# Test artifact");
+
+    await commitArtifacts(ctx, "test commit");
+
+    const log = execSync("git log --oneline", { cwd: repo.dir, encoding: "utf-8" });
+    expect(log).toContain("test commit");
+  });
+
+  it("does not commit when no changes are staged", async () => {
+    const { commitArtifacts, buildIssueContext } = await import("./utils");
+
+    const ctx = buildIssueContext({ number: 2, title: "Test", body: "body" }, "test/repo", ".");
+
+    const issueDir = join(repo.dir, ctx.issueDirRel);
+    mkdirSync(issueDir, { recursive: true });
+
+    const logBefore = execSync("git log --oneline", { cwd: repo.dir, encoding: "utf-8" });
+    await commitArtifacts(ctx, "should not appear");
+    const logAfter = execSync("git log --oneline", { cwd: repo.dir, encoding: "utf-8" });
+
+    expect(logAfter).toBe(logBefore);
+  });
+});

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

@@ -32,12 +32,12 @@ describe("buildIssueContext", () => {
     expect(ctx.scopePath).toBe("src/");
     expect(ctx.issueDirRel).toBe(".auto-claude/issue-42");
     expect(ctx.issueDir).toContain(".auto-claude/issue-42");
-    expect(ctx.branch).toBe("auto-claude/issue-42");
+    expect(ctx.branch).toBe("feature/42-fix-the-bug");
   });
 
-  it("should derive branch name from issue number", () => {
+  it("should derive branch name from issue title", () => {
     const ctx = buildIssueContext({ number: 7, title: "t", body: "" }, "r", ".");
-    expect(ctx.branch).toBe("auto-claude/issue-7");
+    expect(ctx.branch).toBe("feature/7-t");
   });
 });
 
@@ -69,14 +69,14 @@ describe("resolveTemplate", () => {
     const issueDir = join(tmpDir, "issue-99");
     mkdirSync(issueDir, { recursive: true });
 
-    const result = resolveTemplate("01-prompt-research.md", tokens, issueDir);
+    const result = resolveTemplate("01_research.prompt.md", tokens, issueDir);
 
     // Should return a relative path
     expect(result).toContain("issue-99");
-    expect(result).toContain("01-prompt-research.md");
+    expect(result).toContain("01_research.prompt.md");
 
     // Resolved file should exist and have tokens replaced
-    const content = readFileSync(join(issueDir, "01-prompt-research.md"), "utf-8");
+    const content = readFileSync(join(issueDir, "01_research.prompt.md"), "utf-8");
     expect(content).toContain("src/");
     expect(content).toContain(".auto-claude/issue-99");
     expect(content).not.toContain("{{SCOPE_PATH}}");
@@ -120,7 +120,7 @@ describe("buildContextFromArtifacts", () => {
     expect(ctx.title).toBe("My Great Feature");
     expect(ctx.body).toContain("This is the body of the issue.");
     expect(ctx.repo).toBe("test/repo");
-    expect(ctx.branch).toBe("auto-claude/issue-77");
+    expect(ctx.branch).toBe("feature/77-my-great-feature");
   });
 
   it("should fallback title when heading is missing", async () => {

package/src/lib/auto-claude/utils.ts

@@ -1,13 +1,16 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, relative } from "node:path";
+import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 
 import consola from "consola";
 import pc from "picocolors";
 import { x } from "tinyexec";
 
+import { createBranchNameFromIssue } from "../../utils/git/branch-name.js";
 import { getConfig } from "./config.js";
 import { ARTIFACTS } from "./prompt-templates/index.js";
+import { spawnClaude } from "./spawn-claude.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 export const TEMPLATES_DIR = join(__dirname, "prompt-templates");
@@ -63,7 +66,8 @@ export async function runClaude(opts: {
   const args = [
     "-p",
     "--output-format",
-    "json",
+    "stream-json",
+    "--verbose",
     "--permission-mode",
     opts.permissionMode,
     ...(opts.maxTurns ? ["--max-turns", String(opts.maxTurns)] : []),
@@ -76,26 +80,12 @@ export async function runClaude(opts: {
 
   while (true) {
     try {
-      const proc = await x("claude", args, {
-        nodeOptions: { cwd: process.cwd(), stdio: ["ignore", "pipe", "inherit"] },
-        throwOnError: true,
-      });
-      const stdout = proc.stdout;
-
-      try {
-        const parsed = JSON.parse(stdout) as ClaudeResult;
-        consola.success(`Done — ${parsed.num_turns} turns`);
-        if (parsed.result) {
-          consola.log(parsed.result);
-        }
-        return parsed;
-      } catch {
-        consola.warn("Done — failed to parse Claude output");
-        if (stdout.trim()) {
-          consola.log(stdout.trim());
-        }
-        return { result: stdout.trim(), is_error: false, total_cost_usd: 0, num_turns: 0 };
+      const result = await runClaudeStreaming(args);
+      consola.success(`Done — ${result.num_turns} turns`);
+      if (result.result) {
+        consola.log(result.result);
       }
+      return result;
     } catch (e) {
       const shouldRetry = opts.retry ?? cfg.loopRetryEnabled ?? false;
       if (!shouldRetry) throw e;
@@ -113,6 +103,94 @@ export async function runClaude(opts: {
   }
 }
 
+function runClaudeStreaming(args: string[]): Promise<ClaudeResult> {
+  return new Promise((resolve, reject) => {
+    const proc = spawnClaude(args);
+    let capturedResult: ClaudeResult | null = null;
+    let turnCount = 0;
+
+    if (!proc.stdout) {
+      reject(new Error("Claude process has no stdout"));
+      return;
+    }
+
+    const rl = createInterface({ input: proc.stdout });
+
+    rl.on("line", (line) => {
+      if (!line.trim()) return;
+      try {
+        const event = JSON.parse(line) as Record<string, unknown>;
+        handleStreamEvent(event, (turns) => {
+          turnCount = turns;
+        });
+
+        if ("result" in event && "is_error" in event && "num_turns" in event) {
+          capturedResult = {
+            result: String(event.result ?? ""),
+            is_error: Boolean(event.is_error),
+            total_cost_usd: Number(event.total_cost_usd ?? 0),
+            num_turns: Number(event.num_turns),
+          };
+        }
+      } catch {
+        // Skip non-JSON lines
+      }
+    });
+
+    proc.on("error", (err) => {
+      rl.close();
+      reject(err);
+    });
+
+    proc.on("close", (code) => {
+      rl.close();
+      if (capturedResult) {
+        resolve(capturedResult);
+      } else if (code !== 0) {
+        reject(new Error(`Claude process exited with code ${code}`));
+      } else {
+        resolve({ result: "", is_error: false, total_cost_usd: 0, num_turns: turnCount });
+      }
+    });
+  });
+}
+
+function handleStreamEvent(event: Record<string, unknown>, onTurn: (count: number) => void): void {
+  // Tool use events: look for content blocks with tool_use type
+  if (event.type === "assistant" && Array.isArray(event.message)) {
+    for (const block of event.message) {
+      if (
+        typeof block === "object" &&
+        block !== null &&
+        "type" in block &&
+        (block as Record<string, unknown>).type === "tool_use"
+      ) {
+        const name = (block as Record<string, unknown>).name;
+        if (typeof name === "string") {
+          consola.info(`  ${pc.dim("\u21B3")} ${name}`);
+        }
+      }
+    }
+  }
+
+  // Content block with tool_use (alternative format)
+  if (
+    event.type === "content_block_start" &&
+    typeof event.content_block === "object" &&
+    event.content_block !== null
+  ) {
+    const block = event.content_block as Record<string, unknown>;
+    if (block.type === "tool_use" && typeof block.name === "string") {
+      consola.info(`  ${pc.dim("\u21B3")} ${block.name}`);
+    }
+  }
+
+  // Turn count tracking
+  if (typeof event.num_turns === "number" && !("result" in event)) {
+    onTurn(event.num_turns as number);
+  }
+}
+
 // ── Template resolution ──
 
 export interface TokenValues {
@@ -196,7 +274,7 @@ export function buildIssueContext(
     scopePath,
     issueDir: join(process.cwd(), issueDirRel),
     issueDirRel,
-    branch: `auto-claude/issue-${issue.number}`,
+    branch: createBranchNameFromIssue({ number: issue.number, title: issue.title }),
   };
 }
 

package/src/utils/git/branch-name.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { createBranchNameFromIssue } from "./branch-name";
+
+describe("createBranchNameFromIssue", () => {
+  it("creates branch name from issue with basic title", () => {
+    const branchName = createBranchNameFromIssue({
+      number: 4,
+      title: "Long Issue Title - with a lot of words     and stuff ",
+    });
+    expect(branchName).toBe("feature/4-long-issue-title-with-a-lot-of-words-and-stuff");
+  });
+
+  it("handles special characters in title", () => {
+    const branchName = createBranchNameFromIssue({
+      number: 123,
+      title: "Fix bug: @user reported $100 issue!",
+    });
+    expect(branchName).toBe("feature/123-fix-bug-user-reported-100-issue");
+  });
+
+  it("handles title with only numbers", () => {
+    const branchName = createBranchNameFromIssue({ number: 42, title: "123 456" });
+    expect(branchName).toBe("feature/42-123-456");
+  });
+
+  it("trims trailing dashes", () => {
+    const branchName = createBranchNameFromIssue({ number: 7, title: "Update docs ---" });
+    expect(branchName).toBe("feature/7-update-docs");
+  });
+
+  it("handles unicode characters", () => {
+    const branchName = createBranchNameFromIssue({ number: 99, title: "Fix für Übersetzung" });
+    expect(branchName).toBe("feature/99-fix-f-r-bersetzung");
+  });
+
+  it("handles empty-ish title", () => {
+    const branchName = createBranchNameFromIssue({ number: 1, title: "   " });
+    expect(branchName).toBe("feature/1-");
+  });
+
+  it("handles title with underscores", () => {
+    const branchName = createBranchNameFromIssue({ number: 50, title: "snake_case_title" });
+    expect(branchName).toBe("feature/50-snake_case_title");
+  });
+
+  it("handles very long titles", () => {
+    const branchName = createBranchNameFromIssue({
+      number: 200,
+      title: "This is a very long issue title that goes on and on with many words",
+    });
+    expect(branchName).toBe(
+      "feature/200-this-is-a-very-long-issue-title-that-goes-on-and-on-with-many-words",
+    );
+  });
+
+  it("collapses multiple consecutive dashes", () => {
+    const branchName = createBranchNameFromIssue({
+      number: 15,
+      title: "Fix   multiple    spaces",
+    });
+    expect(branchName).toBe("feature/15-fix-multiple-spaces");
+  });
+
+  it("handles title with brackets and parentheses", () => {
+    const branchName = createBranchNameFromIssue({
+      number: 33,
+      title: "[Bug] Fix (critical) issue",
+    });
+    expect(branchName).toBe("feature/33--bug-fix-critical-issue");
+  });
+
+  it("produces same result whether called with minimal or extra fields", () => {
+    const minimal = createBranchNameFromIssue({ number: 90, title: "Add e2e tests" });
+    const withExtras = createBranchNameFromIssue({
+      number: 90,
+      title: "Add e2e tests",
+      state: "open",
+      labels: [],
+    } as { number: number; title: string });
+    expect(minimal).toBe(withExtras);
+    expect(minimal).toBe("feature/90-add-e2e-tests");
+  });
+});

package/src/utils/git/branch-name.ts

@@ -0,0 +1,10 @@
+export function createBranchNameFromIssue(issue: { number: number; title: string }): string {
+  let slug = issue.title.toLowerCase();
+  slug = slug.trim();
+  slug = slug.replaceAll(" ", "-");
+  slug = slug.replace(/[^0-9a-zA-Z_-]/g, "-");
+  slug = slug.replace(/-+/g, "-");
+  slug = slug.replace(/-+$/, "");
+
+  return `feature/${issue.number}-${slug}`;
+}

package/src/lib/auto-claude/prompt-templates/01-prompt-research.md

@@ -1,28 +0,0 @@
-You are a senior developer researching a codebase to prepare for implementing a GitHub issue.
-
-## Your task
-
-Read the issue description in @{{ISSUE_DIR}}/initial-ramblings.md and then **research the codebase in depth** to understand what would be involved in implementing it.
-
-**CRITICAL RULES:**
-
-- Do **NOT** implement the issue. Do not create, modify, or delete any project source files.
-- Your **ONLY** deliverable is writing the file @{{ISSUE_DIR}}/research.md.
-- If the issue seems trivial, research it anyway — document the relevant files, patterns, and context.
-
-## Where to look
-
-The code for this project lives primarily at `{{SCOPE_PATH}}/`. Start your investigation there but explore any related files across the monorepo.
-
-Read every relevant file in full. Understand how the system works deeply — its architecture, data flow, and all its specificities. Do not skim. Do not stop researching until you have a thorough understanding of every part of the codebase that this issue touches.
-
-## What to write in @{{ISSUE_DIR}}/research.md
-
-1. **Relevant files** — every file that would need to be read or modified, with brief descriptions of what each does
-2. **Existing patterns** — how similar features are currently implemented in this codebase (naming conventions, folder structure, component patterns, API patterns)
-3. **Dependencies** — libraries, utilities, shared code, and services that are relevant
-4. **Potential impact areas** — what else might break or need updating (tests, types, imports, configs)
-5. **Edge cases and constraints** — anything tricky that the implementation should watch out for
-6. **Reference implementations** — if there's a similar feature already built, document it as a reference
-
-Be thorough. Keep researching until you have complete understanding — missing information here means a worse plan later.

package/src/lib/auto-claude/prompt-templates/02-prompt-plan.md

@@ -1,28 +0,0 @@
-You are a senior developer planning the implementation for a GitHub issue.
-
-Read the issue in @{{ISSUE_DIR}}/initial-ramblings.md and the research in @{{ISSUE_DIR}}/research.md.
-
-**CRITICAL RULES:**
-
-- Do **NOT** implement the issue. Do not create, modify, or delete any project source files.
-- Your **ONLY** deliverable is writing the file @{{ISSUE_DIR}}/plan.md.
-- Read the actual source files before suggesting changes. Base the plan on what the code actually does, not assumptions.
-
-The code for this project lives primarily at `{{SCOPE_PATH}}/`.
-
-Write @{{ISSUE_DIR}}/plan.md containing:
-
-1. **Summary** — what we're building and why (1-2 paragraphs)
-2. **Approach** — the high-level technical approach chosen
-3. **Architectural decisions** — any significant choices made and why (e.g., which component pattern, state management approach, API structure)
-4. **Key code snippets** — include concrete code examples showing the important parts of the implementation (function signatures, component structure, schema changes, etc.)
-5. **Scope boundaries** — what is explicitly out of scope to keep the change focused
-6. **Risks** — anything that could go wrong or needs special attention during implementation
-7. **Alternative approaches** — a brief section listing other valid ways to solve this problem. For each alternative, include: the approach name, a one-liner on how it works, and why the chosen approach was preferred. Consider industry best practices, common patterns, and obvious alternatives. This section is for PR reviewers only — it will NOT be used in the implementation plan.
-
-**Design principles to follow:**
-
-- Fixing a known issue later instead of now is not simplicity — if the plan touches an area with a known bug, address it.
-- Adding a second primitive for something we already have a primitive for is not simplicity — reuse existing abstractions.
-
-Keep it concise and focused on decisions, not on repeating the research.

package/src/lib/auto-claude/prompt-templates/03-prompt-plan-annotations.md

@@ -1,21 +0,0 @@
-You are a senior developer revising a plan based on reviewer feedback.
-
-Read the current plan in @{{ISSUE_DIR}}/plan.md and the reviewer's annotations in @{{ISSUE_DIR}}/plan-annotations.md.
-
-The original issue is described in @{{ISSUE_DIR}}/initial-ramblings.md and the research is in @{{ISSUE_DIR}}/research.md.
-
-**CRITICAL RULES:**
-
-- Do **NOT** implement the issue. Do not create, modify, or delete any project source files.
-- Your **ONLY** deliverable is updating @{{ISSUE_DIR}}/plan.md to address the annotations.
-
-The code for this project lives primarily at `{{SCOPE_PATH}}/`.
-
-## Instructions
-
-- Read every annotation carefully.
-- Address all the notes — update the plan to incorporate the feedback.
-- If an annotation asks a question, answer it in the plan.
-- If an annotation suggests a different approach, evaluate it and update the plan accordingly.
-- If an annotation points out something missing, add it.
-- Keep the same structure and formatting of the plan, just improve its content.