@towles/tool 0.0.53 → 0.0.55

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 auto-claude pipeline and developer utilities.
 
 ## Installation
 
@@ -26,93 +18,111 @@ 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)
+### Auto-Claude (issue-to-PR pipeline)
 
-| 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                  |
+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.
 
-### Observability
+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.
 
-| Command                   | Description                           |
-| ------------------------- | ------------------------------------- |
-| `tt graph`                | Generate HTML treemap of all sessions |
-| `tt graph --session <id>` | Single session treemap                |
-| `tt graph --open`         | Auto-open in browser                  |
+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).
 
-Treemap colors indicate input/output token ratio: green <2:1, yellow 2-5:1, red >5:1.
+```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
+```
 
-### Git
+**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.
 
-| 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          |
+#### Pipeline Steps
 
-### Journaling
+| 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                               | —                        |
 
-| 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                    |
+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.
 
-### Utilities
+#### 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
+```
 
-| Command      | Alias    | Description                    |
-| ------------ | -------- | ------------------------------ |
-| `tt config`  | `tt cfg` | Show configuration             |
-| `tt doctor`  |          | Check dependencies             |
-| `tt install` |          | Configure Claude Code settings |
+### Observability
 
-## Claude Code Plugin Skills
+| Command                   | Description              |
+| ------------------------- | ------------------------ |
+| `tt graph`                | Token Usage (auto-opens) |
+| `tt graph --session <id>` | Single session           |
+| `tt graph --days 14`      | Filter to last N days    |
 
-Available via `/tt:<command>`:
+### Git
 
-| 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                 |
+| Command              | Description                     |
+| -------------------- | ------------------------------- |
+| `tt gh branch`       | Create branch from GitHub issue |
+| `tt gh pr`           | Create pull request             |
+| `tt gh branch-clean` | Delete merged branches          |
 
-## Development
+### Journaling
 
-```bash
-pnpm start              # Run CLI with tsx
-pnpm test               # Run tests
-pnpm lint               # Run oxlint
-pnpm format             # Format with oxfmt
-pnpm typecheck          # Type check
-```
+| 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 |
 
-### Releasing
+### Utilities
 
-```bash
-gh workflow run release.yml -f bump_type=patch  # or minor/major
-gh run watch
-```
+| Command      | Description                    |
+| ------------ | ------------------------------ |
+| `tt config`  | Show configuration             |
+| `tt doctor`  | Check dependencies             |
+| `tt install` | Configure Claude Code settings |
+
+## 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
+- [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,15 +1,15 @@
 {
   "name": "@towles/tool",
-  "version": "0.0.53",
-  "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": {
@@ -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/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);
+  });
+});