@towles/tool 0.0.53 → 0.0.55

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.

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

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

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

@@ -0,0 +1,33 @@
+You are breaking down a plan into a detailed, ordered implementation checklist.
+
+Read the issue in @{{ISSUE_DIR}}/initial-ramblings.md, the research in @{{ISSUE_DIR}}/research.md, and the plan in @{{ISSUE_DIR}}/plan.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-implementation.md.
+
+The code for this project lives primarily at `{{SCOPE_PATH}}/`.
+
+Write @{{ISSUE_DIR}}/plan-implementation.md with:
+
+- An **ordered task list using markdown checkboxes** (`- [ ]` for each task)
+- Each task should be small enough to implement in one focused session
+- For each task:
+  - **Files to modify** — specific file paths
+  - **What to change** — concrete description of the changes (not vague like "update the component")
+  - **Acceptance criteria** — how to verify this task is done correctly
+- Tasks should be ordered so each builds on the previous (no forward dependencies)
+- Include any necessary setup tasks (new files to create, dependencies to add, etc.)
+- The final task should always be "verify everything works together"
+
+IMPORTANT: Every task MUST use the `- [ ]` checkbox format. Example:
+
+```
+- [ ] **Task 1: Create the API endpoint**
+  - Files: `src/server/routes/foo.ts`
+  - Changes: Add GET /api/foo endpoint that returns...
+  - Acceptance: Endpoint responds with 200 and correct shape
+```
+
+Be specific enough that a developer could follow this checklist without needing to re-read the research or plan.

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

@@ -0,0 +1,31 @@
+You are an implementation agent. Your job is to follow the checklist in @{{ISSUE_DIR}}/plan-implementation.md task by task.
+
+The original issue is described in @{{ISSUE_DIR}}/initial-ramblings.md — this is background context only. Do NOT decide on your own whether the issue is "done". Your ONLY source of truth is the checklist.
+
+The code for this project lives primarily at `{{SCOPE_PATH}}/`.
+
+## How to work
+
+1. Read @{{ISSUE_DIR}}/plan-implementation.md — Find the highest priority (`- [ ]`) task to work. This should be the one YOU decide has the highest priority. Not necessarily the first one
+2. Execute that task (edit files, run commands, whatever the task says)
+3. After completing it, update @{{ISSUE_DIR}}/plan-implementation.md to change `- [ ]` to `- [x]` for that task
+4. Make a git commit ex: `feat(scope): description` or `fix(scope): description`
+5. Move to the next unchecked task. Repeat until all tasks are done or you run out of turns.
+
+Do NOT push to remote — the pipeline handles that.
+Do NOT stop until all tasks and phases are completed.
+
+## When ALL checkboxes are `- [x]`
+
+Write @{{ISSUE_DIR}}/completed-summary.md with a brief summary of everything that was implemented. This file signals completion — do NOT create it if ANY tasks remain unchecked.
+
+## Code quality rules
+
+- Do not add unnecessary comments or jsdocs to code you write.
+- Do not use `any` or `unknown` types — use proper typing.
+- Follow existing codebase patterns and conventions (check nearby files for reference).
+- Do NOT skip tasks just because the end result already looks correct.
+- Follow the checklist literally — if a task says "commit", make a commit. If it says "verify", run the verification.
+- If you encounter something unexpected, use your best judgment and proceed.
+- Fixing a known issue later instead of now is not simplicity — if you see a bug or problem in the area you're working on, fix it.
+- Adding a second primitive for something we already have a primitive for is not simplicity — reuse existing abstractions instead of creating parallel ones (exceptions might exist, but don't use it as an easy way out).

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

@@ -0,0 +1,30 @@
+You are reviewing code changes for the issue described in @{{ISSUE_DIR}}/initial-ramblings.md. The implementation plan in @{{ISSUE_DIR}}/plan-implementation.md describes what should have been done.
+
+Review the changes by running `git diff {{MAIN_BRANCH}}...HEAD` and check for:
+
+1. **Correctness** — do the changes actually implement what the plan describes?
+2. **Missing imports** — are all imports present and correct?
+3. **Type errors** — any obvious TypeScript issues?
+4. **Unused code** — variables, imports, or functions that were added but never used?
+5. **Pattern consistency** — do the changes follow the existing codebase patterns?
+6. **Security issues** — any command injection, XSS, SQL injection, or other vulnerabilities?
+7. **Edge cases** — anything that could break under unusual input or conditions?
+8. **Incomplete work** — TODO comments, placeholder values, or unfinished implementations?
+
+If you find issues:
+
+- Fix them directly (edit the files)
+- Make a separate commit for the fixes: `fix(scope): review fixes for issue #N`
+
+Write your review summary to @{{ISSUE_DIR}}/review.md with:
+
+- **Status**: PASS or PASS WITH FIXES
+- **Issues found** (if any) — what was wrong and what you fixed
+- **Confidence level** — how confident you are the implementation is correct (high/medium/low)
+- **Notes** — anything the PR reviewer should pay attention to
+- **Recommended follow-ups** — only include this section if you discovered genuinely valuable insights during the review. These should be high-signal recommendations, not minor noise. Examples of what qualifies:
+  - An existing primitive/utility that almost does what's needed but requires small changes to be reusable across the codebase
+  - A pattern inconsistency across the codebase that this change exposed
+  - A related improvement that would significantly benefit from the deep context gained during this issue
+  - Technical debt that directly affects the area touched by this change
+    For each follow-up, write it as a potential issue title + 1-2 sentence description of what and why. Omit this section entirely if there's nothing worth flagging.

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

@@ -0,0 +1,39 @@
+You are updating an existing auto-claude branch to be compatible with the latest {{MAIN_BRANCH}}.
+
+## Context
+
+Read these files to understand what this PR is doing:
+
+- Original issue: @{{ISSUE_DIR}}/initial-ramblings.md
+- Implementation plan: @{{ISSUE_DIR}}/plan-implementation.md
+- What was implemented: @{{ISSUE_DIR}}/completed-summary.md
+
+## Your task
+
+1. Run `git diff {{MAIN_BRANCH}}...HEAD` to see what this PR currently changes vs {{MAIN_BRANCH}}
+2. Run `git log {{MAIN_BRANCH}}..HEAD --oneline` to see the PR's commit history
+3. Run `git diff HEAD...{{MAIN_BRANCH}}` to see what {{MAIN_BRANCH}} has changed since this branch diverged
+4. Analyze whether the PR's changes are still valid:
+   - Do imports still resolve? Have moved/renamed files been accounted for?
+   - Do APIs/types used by the PR still exist and have the same signatures?
+   - Are there conflicts with new code on {{MAIN_BRANCH}} that touches the same areas?
+5. If you find issues:
+   - Fix the code directly to work with current {{MAIN_BRANCH}}
+   - Run type-check (`pnpm type-check`) if applicable
+   - Commit fixes: `fix(scope): adapt to {{MAIN_BRANCH}} changes`
+6. If everything looks fine, note that no changes were needed.
+
+The code for this project lives primarily at `{{SCOPE_PATH}}/`.
+
+**CRITICAL RULES:**
+
+- Do NOT re-implement the feature. Only fix what's broken due to {{MAIN_BRANCH}} changes.
+- If {{MAIN_BRANCH}} has changed so fundamentally that the PR's approach is no longer viable (e.g., the module was refactored, APIs were replaced entirely), do NOT attempt to force a fix. Report `NEEDS-ATTENTION` with a clear explanation of what changed and why the current implementation can't be salvaged with minor fixes.
+- Do NOT push to remote — the pipeline handles that.
+- Do NOT modify the plan or research files.
+
+Write a summary of what you did to @{{ISSUE_DIR}}/refresh-summary.md with:
+
+- **Status**: UP-TO-DATE, ADAPTED, or NEEDS-ATTENTION
+- **Changes made** (if any) — what broke and how you fixed it
+- **Risk areas** — anything a reviewer should double-check

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

@@ -0,0 +1,145 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { ARTIFACTS, PIPELINE_STEPS, STEP_LABELS, STEP_NAMES, TEMPLATES } from "./index";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+describe("TEMPLATES", () => {
+  it("should have all expected keys", () => {
+    expect(Object.keys(TEMPLATES)).toEqual([
+      "research",
+      "plan",
+      "planAnnotations",
+      "planImplementation",
+      "implement",
+      "review",
+      "refresh",
+    ]);
+  });
+
+  it("every template file should exist on disk", () => {
+    for (const [key, filename] of Object.entries(TEMPLATES)) {
+      const fullPath = join(__dirname, filename);
+      expect(existsSync(fullPath), `TEMPLATES.${key} → ${filename} missing`).toBe(true);
+    }
+  });
+
+  it("filenames should follow XX-prompt-*.md pattern", () => {
+    for (const filename of Object.values(TEMPLATES)) {
+      expect(filename).toMatch(/^\d{2}-prompt-.+\.md$/);
+    }
+  });
+
+  it("filenames should be in ascending numeric order", () => {
+    const numbers = Object.values(TEMPLATES).map((f) => Number.parseInt(f.slice(0, 2), 10));
+    for (let i = 1; i < numbers.length; i++) {
+      expect(numbers[i]).toBeGreaterThan(numbers[i - 1]);
+    }
+  });
+});
+
+describe("PIPELINE_STEPS", () => {
+  it("should have 8 steps", () => {
+    expect(PIPELINE_STEPS).toHaveLength(8);
+  });
+
+  it("each step should have order, name, and label", () => {
+    for (const step of PIPELINE_STEPS) {
+      expect(step).toHaveProperty("order");
+      expect(step).toHaveProperty("name");
+      expect(step).toHaveProperty("label");
+      expect(typeof step.order).toBe("number");
+      expect(typeof step.name).toBe("string");
+      expect(typeof step.label).toBe("string");
+    }
+  });
+
+  it("order should be sequential starting from 1", () => {
+    for (let i = 0; i < PIPELINE_STEPS.length; i++) {
+      expect(PIPELINE_STEPS[i].order).toBe(i + 1);
+    }
+  });
+
+  it("names should match expected pipeline order", () => {
+    expect(PIPELINE_STEPS.map((s) => s.name)).toEqual([
+      "research",
+      "plan",
+      "plan-annotations",
+      "plan-implementation",
+      "implement",
+      "review",
+      "create-pr",
+      "remove-label",
+    ]);
+  });
+
+  it("labels should include the order number", () => {
+    for (const step of PIPELINE_STEPS) {
+      const prefix = String(step.order).padStart(2, "0");
+      expect(step.label.startsWith(prefix), `${step.label} should start with ${prefix}`).toBe(true);
+    }
+  });
+});
+
+describe("STEP_NAMES", () => {
+  it("should be derived from PIPELINE_STEPS", () => {
+    expect(STEP_NAMES).toEqual(PIPELINE_STEPS.map((s) => s.name));
+  });
+});
+
+describe("STEP_LABELS", () => {
+  it("should have camelCase keys for all pipeline steps plus refresh", () => {
+    expect(Object.keys(STEP_LABELS)).toEqual([
+      "research",
+      "plan",
+      "planAnnotations",
+      "planImplementation",
+      "implement",
+      "review",
+      "createPr",
+      "removeLabel",
+      "refresh",
+    ]);
+  });
+
+  it("pipeline labels should have numeric prefixes", () => {
+    const pipelineLabels = { ...STEP_LABELS };
+    delete pipelineLabels.refresh;
+
+    for (const label of Object.values(pipelineLabels)) {
+      expect(label).toMatch(/^\d{2}-/);
+    }
+  });
+
+  it("should match labels from PIPELINE_STEPS", () => {
+    for (const step of PIPELINE_STEPS) {
+      const values = Object.values(STEP_LABELS);
+      expect(values).toContain(step.label);
+    }
+  });
+});
+
+describe("ARTIFACTS", () => {
+  it("should have all expected keys", () => {
+    expect(Object.keys(ARTIFACTS)).toEqual([
+      "initialRamblings",
+      "research",
+      "plan",
+      "planAnnotations",
+      "planAnnotationsAddressed",
+      "planImplementation",
+      "completedSummary",
+      "review",
+    ]);
+  });
+
+  it("all values should be .md filenames", () => {
+    for (const filename of Object.values(ARTIFACTS)) {
+      expect(filename).toMatch(/^[\w-]+\.md$/);
+    }
+  });
+});

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

@@ -0,0 +1,44 @@
+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",
+} as const;
+
+export const PIPELINE_STEPS = [
+  { order: 1, name: "research", label: "01-Research" },
+  { order: 2, name: "plan", label: "02-Plan" },
+  { order: 3, name: "plan-annotations", label: "03-Plan-Annotations" },
+  { order: 4, name: "plan-implementation", label: "04-Plan-Implementation" },
+  { order: 5, name: "implement", label: "05-Implement" },
+  { order: 6, name: "review", label: "06-Review" },
+  { order: 7, name: "create-pr", label: "07-Create PR" },
+  { order: 8, name: "remove-label", label: "08-Remove Label" },
+] as const;
+
+export type StepName = (typeof PIPELINE_STEPS)[number]["name"];
+export const STEP_NAMES = PIPELINE_STEPS.map((s) => s.name);
+
+function toCamelCase(s: string): string {
+  return s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/** Keyed lookup for step labels (includes standalone "refresh" step) */
+export const STEP_LABELS = {
+  ...Object.fromEntries(PIPELINE_STEPS.map((s) => [toCamelCase(s.name), s.label])),
+  refresh: "Refresh",
+} as Record<string, string>;
+
+export const ARTIFACTS = {
+  initialRamblings: "initial-ramblings.md",
+  research: "research.md",
+  plan: "plan.md",
+  planAnnotations: "plan-annotations.md",
+  planAnnotationsAddressed: "plan-annotations-addressed.md",
+  planImplementation: "plan-implementation.md",
+  completedSummary: "completed-summary.md",
+  review: "review.md",
+} as const;

package/src/lib/auto-claude/steps/create-pr.ts

@@ -0,0 +1,93 @@
+import { join } from "node:path";
+
+import consola from "consola";
+
+import { getConfig } from "../config.js";
+import { ARTIFACTS, STEP_LABELS } from "../prompt-templates/index.js";
+import { fileExists, ghRaw, git, log, logStep, readFile } from "../utils.js";
+import type { IssueContext } from "../utils.js";
+
+export async function stepCreatePR(ctx: IssueContext): Promise<boolean> {
+  const cfg = getConfig();
+
+  if (await hasOpenPR(ctx.branch)) {
+    logStep(STEP_LABELS.createPr, ctx, true);
+    return true;
+  }
+
+  logStep(STEP_LABELS.createPr, ctx);
+
+  await git(["push", "-u", cfg.remote, ctx.branch]);
+
+  const reviewPath = join(ctx.issueDir, ARTIFACTS.review);
+  const reviewSummary = fileExists(reviewPath)
+    ? readFile(reviewPath).slice(0, 2000)
+    : "No review summary available.";
+
+  const body = [
+    "## Summary",
+    "",
+    `Automated implementation for: **${ctx.title}**`,
+    "",
+    `Closes #${ctx.number}`,
+    "",
+    "## Pipeline Artifacts",
+    "",
+    `- Research: \`.auto-claude/issue-${ctx.number}/research.md\``,
+    `- Plan: \`.auto-claude/issue-${ctx.number}/plan.md\``,
+    `- Implementation Plan: \`.auto-claude/issue-${ctx.number}/plan-implementation.md\``,
+    `- Review: \`.auto-claude/issue-${ctx.number}/review.md\``,
+    "",
+    "## Review Summary",
+    "",
+    reviewSummary,
+    "",
+    "---",
+    "Generated by auto-claude pipeline",
+  ].join("\n");
+
+  const prUrl = await ghRaw([
+    "pr",
+    "create",
+    "--repo",
+    cfg.repo,
+    "--head",
+    ctx.branch,
+    "--title",
+    ctx.title,
+    "--body",
+    body,
+    "--label",
+    cfg.triggerLabel,
+  ]);
+
+  if (prUrl) {
+    log(`PR created: ${prUrl}`);
+  } else {
+    consola.error("Failed to create PR");
+    return false;
+  }
+
+  return true;
+}
+
+async function hasOpenPR(branch: string): Promise<boolean> {
+  const out = await ghRaw([
+    "pr",
+    "list",
+    "--repo",
+    getConfig().repo,
+    "--head",
+    branch,
+    "--state",
+    "open",
+    "--json",
+    "number",
+  ]);
+  try {
+    const prs = JSON.parse(out);
+    return Array.isArray(prs) && prs.length > 0;
+  } catch {
+    return false;
+  }
+}

package/src/lib/auto-claude/steps/fetch-issues.ts

@@ -0,0 +1,64 @@
+import { getConfig } from "../config.js";
+import { buildIssueContext, gh, log } from "../utils.js";
+import type { IssueContext } from "../utils.js";
+
+interface GhIssue {
+  number: number;
+  title: string;
+  body: string;
+  labels: { name: string }[];
+}
+
+export async function fetchIssues(limit?: number): Promise<IssueContext[]> {
+  const cfg = getConfig();
+
+  log(`Scanning ${cfg.repo} for issues labeled "${cfg.triggerLabel}"...`);
+
+  let issues: GhIssue[];
+  try {
+    issues = await gh<GhIssue[]>([
+      "issue",
+      "list",
+      "--repo",
+      cfg.repo,
+      "--label",
+      cfg.triggerLabel,
+      "--state",
+      "open",
+      "--json",
+      "number,title,body,labels",
+    ]);
+  } catch (e) {
+    log(`Warning: could not fetch issues from ${cfg.repo}: ${e}`);
+    return [];
+  }
+
+  if (issues.length === 0) {
+    log("No issues found.");
+    return [];
+  }
+
+  log(`Found ${issues.length} issue(s).`);
+
+  const selected = limit != null ? issues.slice(0, limit) : issues;
+  return selected.map((issue) => buildIssueContext(issue, cfg.repo, cfg.scopePath));
+}
+
+export async function fetchIssue(issueNumber: number): Promise<IssueContext | undefined> {
+  const cfg = getConfig();
+
+  try {
+    const issue = await gh<GhIssue>([
+      "issue",
+      "view",
+      String(issueNumber),
+      "--repo",
+      cfg.repo,
+      "--json",
+      "number,title,body,labels",
+    ]);
+    return buildIssueContext(issue, cfg.repo, cfg.scopePath);
+  } catch {
+    return undefined;
+  }
+}