@towles/tool 0.0.54 → 0.0.55

package/README.md

@@ -1,6 +1,6 @@
 # Towles Tool
 
-Personal CLI toolkit with autonomous task runner and developer utilities.
+Personal CLI toolkit with auto-claude pipeline and developer utilities.
 
 ## Installation
 
@@ -23,17 +23,58 @@ pnpm start
 
 ## CLI Commands
 
-### Ralph (autonomous runner)
+### Auto-Claude (issue-to-PR pipeline)
 
-| 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      |
+A fully autonomous issue-to-PR pipeline — what a more productizable version of the ralph planning/execution loop looks like. Cloud-based agents (GitHub Copilot, Anthropic agents) can create PRs but can't run your full stack — Docker, Postgres, Playwright, Chrome DevTools MCP, etc. Running locally gives Claude access to the complete environment to run, test, and iterate.
+
+Label issues with `auto-claude`, start the loop, and walk away. Queue up multiple issues during the day and let them run overnight, or tag an issue from your phone or the Claude mobile app and have it waiting as a PR by morning.
+
+Inspired by [Boris Tane's workflow](https://boristane.com/blog/how-i-use-claude-code/) and [Francisco Hermida's auto-pr](https://github.com/franciscohermida/auto-pr).
+
+```bash
+tt auto-claude --issue 42                # Process specific issue
+tt auto-claude --issue 42 --until plan   # Stop after planning step
+tt auto-claude --refresh --issue 42      # Rebase stale PR branch
+tt auto-claude --reset 42               # Reset state for an issue
+tt auto-claude --loop                    # Start polling loop
+```
+
+**Slot-based workflow:** Run auto-claude in a dedicated clone of the repo — not the one you're actively editing. Keep 3-5 clones (e.g. `slot-1`, `slot-2`, `slot-primary`) so each issue gets its own isolated environment. `slot-primary` is typically the one open in VS Code for manual work; the numbered slots run auto-claude independently. Each slot has its own `.env` so services and ports don't collide between slots. Claude Code's worktree feature may replace this approach in the future, but full repo clones have been more reliable in practice.
+
+#### Pipeline Steps
+
+| Step                    | What it does                                                                                     | Artifact produced        |
+| ----------------------- | ------------------------------------------------------------------------------------------------ | ------------------------ |
+| **research**            | Deep-reads the codebase for context relevant to the issue                                        | `research.md`            |
+| **plan**                | High-level technical plan with architectural decisions and alternatives                          | `plan.md`                |
+| **plan-annotations**    | _(optional)_ Addresses reviewer feedback if `plan-annotations.md` exists                         | updates `plan.md`        |
+| **plan-implementation** | Breaks plan into an ordered checkbox task list                                                   | `plan-implementation.md` |
+| **implement**           | Executes tasks one-by-one, checking boxes and committing as it goes (loops up to 100 iterations) | `completed-summary.md`   |
+| **review**              | Self-reviews the diff, fixes issues, rates confidence                                            | `review.md`              |
+| **create-pr**           | Pushes branch and opens a PR with artifact links and review summary                              | GitHub PR                |
+| **remove-label**        | Removes the `auto-claude` label so the issue isn't picked up again                               | —                        |
+
+All artifacts are written to `.auto-claude/issue-{N}/`. Use `--until <step>` to pause after any step (e.g. `--until plan` to review before implementation). The plan-annotations step lets you drop feedback into `plan-annotations.md` and re-run — the pipeline will revise the plan before continuing.
+
+#### How it works under the hood
+
+1. **Auto-detects** repo (`gh repo view`) and main branch (`git symbolic-ref`) from cwd — no config file needed
+2. **Creates a branch** `auto-claude/issue-{N}` from main
+3. **Runs Claude Code CLI** (`claude -p`) in print mode with JSON output for each step, using prompt templates with token replacement (`{{ISSUE_DIR}}`, `{{SCOPE_PATH}}`, `{{MAIN_BRANCH}}`)
+4. **Artifacts drive state** — each step checks if its output file exists before running (idempotent). Resume after a crash by re-running the same command
+5. **Returns to main** after each issue completes or fails
+
+#### Code layout
+
+```
+src/commands/auto-claude.ts          # oclif command (alias: ac)
+src/lib/auto-claude/
+  config.ts                          # Zod schema, initConfig(), getConfig()
+  utils.ts                           # exec helpers, runClaude, templates, IssueContext
+  pipeline.ts                        # step orchestration
+  steps/                             # one file per pipeline step
+  prompt-templates/                  # 7 .md prompt files with {{TOKEN}} placeholders
+```
 
 ### Observability
 
@@ -79,7 +120,6 @@ pnpm start
 ## Guidelines
 
 - [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
 

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@towles/tool",
-  "version": "0.0.54",
-  "description": "CLI tool with autonomous task runner (ralph), observability, and quality-of-life commands for daily development.",
+  "version": "0.0.55",
+  "description": "CLI tool with auto-claude pipeline, developer tools, and journaling via markdown.",
   "keywords": [
+    "auto-claude",
     "autonomic",
     "claude",
     "cli",
     "git",
     "journal",
-    "oclif",
-    "ralph"
+    "oclif"
   ],
   "homepage": "https://github.com/ChrisTowles/towles-tool#readme",
   "bugs": {

package/src/commands/auto-claude.ts

@@ -0,0 +1,219 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+
+import { Flags } from "@oclif/core";
+import consola from "consola";
+
+import { BaseCommand } from "./base.js";
+import {
+  STEP_NAMES,
+  buildIssueContext,
+  fetchIssue,
+  fetchIssues,
+  getConfig,
+  git,
+  initConfig,
+  log,
+  runPipeline,
+  sleep,
+  stepRefresh,
+} from "../lib/auto-claude/index.js";
+import type { IssueContext, StepName } from "../lib/auto-claude/index.js";
+
+export default class AutoClaude extends BaseCommand {
+  static override aliases = ["ac"];
+
+  static override description = "Automated issue-to-PR pipeline using Claude Code";
+
+  static override examples = [
+    {
+      description: "Process a specific issue",
+      command: "<%= config.bin %> auto-claude --issue 42",
+    },
+    {
+      description: "Run until plan step",
+      command: "<%= config.bin %> auto-claude --issue 42 --until plan",
+    },
+    {
+      description: "Reset local state for an issue",
+      command: "<%= config.bin %> auto-claude --reset 42",
+    },
+    {
+      description: "Refresh a stale PR branch",
+      command: "<%= config.bin %> auto-claude --refresh --issue 42",
+    },
+    {
+      description: "Loop mode: poll for labeled issues",
+      command: "<%= config.bin %> auto-claude --loop",
+    },
+    {
+      description: "Loop with custom interval",
+      command: "<%= config.bin %> auto-claude --loop --interval 45",
+    },
+  ];
+
+  static override flags = {
+    ...BaseCommand.baseFlags,
+    issue: Flags.integer({
+      char: "i",
+      description: "Process a specific issue number",
+    }),
+    until: Flags.string({
+      char: "u",
+      description: `Stop after this step (${STEP_NAMES.join(", ")})`,
+      options: [...STEP_NAMES],
+    }),
+    reset: Flags.integer({
+      description: "Delete local state for an issue (force restart)",
+    }),
+    refresh: Flags.boolean({
+      description: "Rebase a stale PR branch onto current main",
+      default: false,
+    }),
+    loop: Flags.boolean({
+      description: "Poll for labeled issues continuously",
+      default: false,
+    }),
+    interval: Flags.integer({
+      description: "Poll interval in minutes (default: 30)",
+    }),
+    limit: Flags.integer({
+      description: "Max issues per iteration (default: 1)",
+      default: 1,
+    }),
+    label: Flags.string({
+      description: "Trigger label (default: auto-claude)",
+    }),
+    "main-branch": Flags.string({
+      description: "Override main branch detection",
+    }),
+    "scope-path": Flags.string({
+      description: "Path within repo to scope work (default: .)",
+    }),
+  };
+
+  async run(): Promise<void> {
+    const { flags } = await this.parse(AutoClaude);
+
+    const cfg = await initConfig({
+      triggerLabel: flags.label,
+      mainBranch: flags["main-branch"],
+      scopePath: flags["scope-path"],
+      loopRetryEnabled: flags.loop || undefined,
+    });
+
+    if (flags.reset) {
+      const issueDir = join(process.cwd(), `.auto-claude/issue-${flags.reset}`);
+      log(`Resetting state for issue-${flags.reset}...`);
+      rmSync(issueDir, { recursive: true, force: true });
+      log(`Cleaned ${issueDir}`);
+      return;
+    }
+
+    if (flags.refresh) {
+      if (!flags.issue) {
+        this.error("--refresh requires --issue <number>");
+      }
+      const ctx = buildIssueContext(
+        { number: flags.issue, title: `Issue #${flags.issue}`, body: "" },
+        cfg.repo,
+        cfg.scopePath,
+      );
+      await stepRefresh(ctx);
+      return;
+    }
+
+    const untilStep = flags.until as StepName | undefined;
+    const loopMode = flags.loop;
+    const intervalMs = (flags.interval ?? cfg.loopIntervalMinutes) * 60_000;
+    const limit = flags.limit ?? 1;
+
+    if (loopMode) {
+      registerShutdownHandlers();
+      log(`Loop mode — interval: ${intervalMs / 60_000}min, limit: ${limit}`);
+    }
+
+    let iteration = 0;
+
+    do {
+      const iterationStart = Date.now();
+      iteration++;
+
+      if (loopMode) {
+        consola.box({ title: `Iteration #${iteration}`, message: new Date().toISOString() });
+      }
+
+      try {
+        await syncWithRemote();
+      } catch (e) {
+        log(`Sync failed: ${e instanceof Error ? e.message : String(e)}`);
+        if (loopMode) {
+          log(`Will retry in ${Math.round(intervalMs / 1000)}s...`);
+          await sleep(intervalMs);
+          continue;
+        }
+        throw e;
+      }
+
+      let contexts: IssueContext[];
+      if (flags.issue) {
+        const ctx = await fetchIssue(flags.issue);
+        contexts = ctx ? [ctx] : [];
+      } else {
+        contexts = await fetchIssues(limit);
+      }
+
+      if (contexts.length === 0) {
+        log("No issues to process.");
+      } else {
+        log(`Processing ${contexts.length} issue(s)...\n`);
+
+        for (const ctx of contexts) {
+          try {
+            await runPipeline(ctx, untilStep);
+          } catch (e) {
+            consola.error(`Pipeline error for ${ctx.repo}#${ctx.number}:`, e);
+          }
+        }
+      }
+
+      if (loopMode) {
+        const waitMs = Math.max(0, intervalMs - (Date.now() - iterationStart));
+        if (waitMs > 0) {
+          log(`Waiting ${Math.round(waitMs / 1000)}s until next iteration...`);
+          await sleep(waitMs);
+        }
+      }
+    } while (loopMode);
+
+    log("Done.");
+  }
+}
+
+async function syncWithRemote(): Promise<void> {
+  const cfg = getConfig();
+  log("Syncing with remote...");
+  await git(["fetch", "--all", "--prune"]);
+  const branch = await git(["rev-parse", "--abbrev-ref", "HEAD"]);
+  if (branch !== cfg.mainBranch) {
+    log(`Warning: on branch "${branch}", switching to ${cfg.mainBranch}...`);
+    await git(["checkout", cfg.mainBranch]).catch(() => {});
+  }
+  const status = await git(["status", "--porcelain"]);
+  if (status.length > 0) {
+    throw new Error("Working tree has uncommitted changes. Commit or stash them first.");
+  }
+  await git(["pull", cfg.remote, cfg.mainBranch]);
+}
+
+function registerShutdownHandlers(): void {
+  for (const signal of ["SIGINT", "SIGTERM"] as const) {
+    process.on(signal, () => {
+      log(`Received ${signal}, shutting down...`);
+      setTimeout(() => process.exit(1), 5_000).unref();
+      git(["checkout", getConfig().mainBranch])
+        .catch(() => {})
+        .then(() => process.exit(0));
+    });
+  }
+}

package/src/commands/doctor.ts

@@ -1,5 +1,3 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
 import { x } from "tinyexec";
 import pc from "picocolors";
 import { BaseCommand } from "./base.js";
@@ -63,19 +61,8 @@ export default class Doctor extends BaseCommand {
       }
     }
 
-    // Check ralph files in .gitignore
-    this.log("");
-    const gitignoreCheck = this.checkRalphGitignore();
-    const gitignoreIcon = gitignoreCheck.ok ? pc.green("✓") : pc.yellow("⚠");
-    this.log(
-      `${gitignoreIcon} .gitignore: ${gitignoreCheck.ok ? "ralph-* excluded" : "ralph-* NOT excluded"}`,
-    );
-    if (!gitignoreCheck.ok) {
-      this.log(`  ${pc.dim('Add "ralph-*" to .gitignore to exclude local ralph state files')}`);
-    }
-
     // Summary
-    const allOk = checks.every((c) => c.ok) && ghAuth.ok && gitignoreCheck.ok;
+    const allOk = checks.every((c) => c.ok) && ghAuth.ok;
     this.log("");
     if (allOk) {
       this.log(pc.green("All checks passed!"));
@@ -113,24 +100,4 @@ export default class Doctor extends BaseCommand {
       return { ok: false };
     }
   }
-
-  private checkRalphGitignore(): { ok: boolean } {
-    const gitignorePath = path.join(process.cwd(), ".gitignore");
-    try {
-      if (!fs.existsSync(gitignorePath)) {
-        return { ok: false };
-      }
-      const content = fs.readFileSync(gitignorePath, "utf-8");
-      // Check for ralph-* pattern or specific ralph files
-      const hasRalphPattern = content.split("\n").some((line) => {
-        const trimmed = line.trim();
-        return (
-          trimmed === "ralph-*" || trimmed === "ralph-*.json" || trimmed === "ralph-state.json"
-        );
-      });
-      return { ok: hasRalphPattern };
-    } catch {
-      return { ok: false };
-    }
-  }
 }

package/src/config/settings.ts

@@ -13,13 +13,6 @@ export const DEFAULT_CONFIG_DIR = path.join(homedir(), ".config", TOOL_NAME);
 /** User settings file path */
 export const USER_SETTINGS_PATH = path.join(DEFAULT_CONFIG_DIR, `${TOOL_NAME}.settings.json`);
 
-export const RalphSettingsSchema = z.object({
-  // Base directory for ralph files (relative to cwd or absolute)
-  stateDir: z.string().default("./.claude/.ralph"),
-});
-
-export type RalphSettings = z.infer<typeof RalphSettingsSchema>;
-
 export const JournalSettingsSchema = z.object({
   // Base folder where all journal files are stored
   baseFolder: z.string().default(path.join(homedir())),
@@ -48,9 +41,6 @@ export const UserSettingsSchema = z.object({
   journalSettings: JournalSettingsSchema.optional().transform(
     (v) => v ?? JournalSettingsSchema.parse({}),
   ),
-  ralphSettings: RalphSettingsSchema.optional().transform(
-    (v) => v ?? RalphSettingsSchema.parse({}),
-  ),
 });
 
 type UserSettings = z.infer<typeof UserSettingsSchema>;

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

@@ -0,0 +1,53 @@
+import { afterEach, describe, expect, it } from "vitest";
+
+import { AutoClaudeConfigSchema, getConfig, initConfig } from "./config";
+
+describe("AutoClaudeConfigSchema", () => {
+  it("should apply all defaults when only repo is provided", () => {
+    const cfg = AutoClaudeConfigSchema.parse({ repo: "owner/repo" });
+
+    expect(cfg.triggerLabel).toBe("auto-claude");
+    expect(cfg.scopePath).toBe(".");
+    expect(cfg.mainBranch).toBe("main");
+    expect(cfg.remote).toBe("origin");
+    expect(cfg.maxImplementIterations).toBe(5);
+    expect(cfg.maxTurns).toBeUndefined();
+    expect(cfg.loopIntervalMinutes).toBe(30);
+    expect(cfg.loopRetryEnabled).toBe(false);
+    expect(cfg.maxRetries).toBe(5);
+    expect(cfg.retryDelayMs).toBe(30_000);
+    expect(cfg.maxRetryDelayMs).toBe(300_000);
+  });
+
+  it("should allow overriding defaults", () => {
+    const cfg = AutoClaudeConfigSchema.parse({
+      repo: "owner/repo",
+      triggerLabel: "bot",
+      maxImplementIterations: 10,
+      maxRetries: 3,
+      loopRetryEnabled: true,
+    });
+
+    expect(cfg.triggerLabel).toBe("bot");
+    expect(cfg.maxImplementIterations).toBe(10);
+    expect(cfg.maxRetries).toBe(3);
+    expect(cfg.loopRetryEnabled).toBe(true);
+  });
+
+  it("should require repo field", () => {
+    expect(() => AutoClaudeConfigSchema.parse({})).toThrow();
+  });
+});
+
+describe("getConfig", () => {
+  afterEach(() => {
+    // Reset internal config state by re-initializing
+  });
+
+  it("should return config after initConfig with explicit repo and mainBranch", async () => {
+    await initConfig({ repo: "test/repo", mainBranch: "main" });
+    const cfg = getConfig();
+    expect(cfg.repo).toBe("test/repo");
+    expect(cfg.mainBranch).toBe("main");
+  });
+});

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

@@ -0,0 +1,68 @@
+import consola from "consola";
+import { x } from "tinyexec";
+import { z } from "zod/v4";
+
+export const AutoClaudeConfigSchema = z.object({
+  triggerLabel: z.string().default("auto-claude"),
+  repo: z.string(),
+  scopePath: z.string().default("."),
+  mainBranch: z.string().default("main"),
+  remote: z.string().default("origin"),
+  maxImplementIterations: z.number().default(5),
+  maxTurns: z.number().optional(),
+  loopIntervalMinutes: z.number().default(30),
+  loopRetryEnabled: z.boolean().default(false),
+  maxRetries: z.number().default(5),
+  retryDelayMs: z.number().default(30_000),
+  maxRetryDelayMs: z.number().default(300_000),
+});
+
+export type AutoClaudeConfig = z.infer<typeof AutoClaudeConfigSchema>;
+
+let _config: AutoClaudeConfig | undefined;
+
+export async function initConfig(
+  overrides: Partial<AutoClaudeConfig> = {},
+): Promise<AutoClaudeConfig> {
+  // Auto-detect repo
+  let repo = overrides.repo;
+  if (!repo) {
+    const result = await x(
+      "gh",
+      ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"],
+      {
+        nodeOptions: { cwd: process.cwd() },
+        throwOnError: true,
+      },
+    );
+    repo = result.stdout.trim();
+  }
+  consola.info(`Detected repo: ${repo}`);
+
+  // Auto-detect main branch
+  let mainBranch = overrides.mainBranch;
+  if (!mainBranch) {
+    try {
+      const result = await x("git", ["symbolic-ref", "refs/remotes/origin/HEAD"], {
+        nodeOptions: { cwd: process.cwd() },
+        throwOnError: true,
+      });
+      mainBranch = result.stdout.trim().replace("refs/remotes/origin/", "");
+    } catch {
+      mainBranch = "main";
+    }
+  }
+
+  _config = AutoClaudeConfigSchema.parse({
+    ...overrides,
+    repo,
+    mainBranch,
+  });
+
+  return _config;
+}
+
+export function getConfig(): AutoClaudeConfig {
+  if (!_config) throw new Error("Config not initialized. Call initConfig() first.");
+  return _config;
+}

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

@@ -0,0 +1,14 @@
+export { type AutoClaudeConfig, AutoClaudeConfigSchema, getConfig, initConfig } from "./config.js";
+export { STEP_NAMES, runPipeline } from "./pipeline.js";
+export type { StepName } from "./prompt-templates/index.js";
+export { fetchIssue, fetchIssues } from "./steps/fetch-issues.js";
+export { stepRefresh } from "./steps/refresh.js";
+export {
+  type IssueContext,
+  buildContextFromArtifacts,
+  buildIssueContext,
+  ensureBranch,
+  git,
+  log,
+  sleep,
+} from "./utils.js";

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

@@ -0,0 +1,14 @@
+import { describe, expect, it } from "vitest";
+
+import { STEP_NAMES } from "./pipeline";
+import { PIPELINE_STEPS } from "./prompt-templates/index";
+
+describe("STEP_NAMES", () => {
+  it("should be derived from PIPELINE_STEPS", () => {
+    expect(STEP_NAMES).toEqual(PIPELINE_STEPS.map((s) => s.name));
+  });
+
+  it("should have 8 steps", () => {
+    expect(STEP_NAMES).toHaveLength(8);
+  });
+});

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

@@ -0,0 +1,64 @@
+import { join } from "node:path";
+
+import { getConfig } from "./config.js";
+import { ARTIFACTS, PIPELINE_STEPS } from "./prompt-templates/index.js";
+import type { StepName } from "./prompt-templates/index.js";
+import { stepCreatePR } from "./steps/create-pr.js";
+import { stepImplement } from "./steps/implement.js";
+import { stepPlanAnnotations } from "./steps/plan-annotations.js";
+import { stepPlanImplementation } from "./steps/plan-implementation.js";
+import { stepPlan } from "./steps/plan.js";
+import { stepRemoveLabel } from "./steps/remove-label.js";
+import { stepResearch } from "./steps/research.js";
+import { stepReview } from "./steps/review.js";
+import { ensureDir, fileExists, git, log, writeFile } from "./utils.js";
+import type { IssueContext } from "./utils.js";
+
+const STEP_RUNNERS: Record<StepName, (ctx: IssueContext) => Promise<boolean>> = {
+  research: stepResearch,
+  plan: stepPlan,
+  "plan-annotations": stepPlanAnnotations,
+  "plan-implementation": stepPlanImplementation,
+  implement: stepImplement,
+  review: stepReview,
+  "create-pr": stepCreatePR,
+  "remove-label": stepRemoveLabel,
+};
+
+export { type StepName, STEP_NAMES } from "./prompt-templates/index.js";
+
+export async function runPipeline(ctx: IssueContext, untilStep?: StepName): Promise<void> {
+  log(`Pipeline starting for ${ctx.repo}#${ctx.number}: ${ctx.title}`);
+
+  ensureDir(ctx.issueDir);
+  const ramblingsPath = join(ctx.issueDir, ARTIFACTS.initialRamblings);
+  if (!fileExists(ramblingsPath)) {
+    const content = `# ${ctx.title}\n\n> ${ctx.repo}#${ctx.number}\n\n${ctx.body ?? ""}`;
+    writeFile(ramblingsPath, content);
+    log("Saved initial-ramblings.md");
+  }
+
+  for (const step of PIPELINE_STEPS) {
+    const runner = STEP_RUNNERS[step.name];
+    const success = await runner(ctx);
+
+    if (!success) {
+      log(`Pipeline stopped at "${step.name}" for ${ctx.repo}#${ctx.number}`);
+      await checkoutMain();
+      return;
+    }
+
+    if (untilStep && step.name === untilStep) {
+      log(`Pipeline paused after "${step.name}" (--until ${untilStep})`);
+      await checkoutMain();
+      return;
+    }
+  }
+
+  log(`Pipeline complete for ${ctx.repo}#${ctx.number}`);
+  await checkoutMain();
+}
+
+async function checkoutMain(): Promise<void> {
+  await git(["checkout", getConfig().mainBranch]).catch(() => {});
+}

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

@@ -0,0 +1,28 @@
+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

@@ -0,0 +1,28 @@
+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.