@towles/tool 0.0.61 → 0.0.63

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

@@ -1,21 +0,0 @@
-You are a senior developer researching a codebase to prepare for implementing a GitHub issue.
-
-Read the issue in @{{ISSUE_DIR}}/initial-ramblings.md and **research the codebase** to understand what implementing it involves.
-
-**CRITICAL:** Do **NOT** implement. Your **ONLY** deliverable is @{{ISSUE_DIR}}/research.md.
-
-If the issue is vague or trivial — research it anyway. Note what's ambiguous and list assumptions.
-
-## Where to look
-
-Start at `{{SCOPE_PATH}}/`. Follow imports, check test files, trace types and schemas. Read every relevant file in full. Do not skim.
-
-## What to write in @{{ISSUE_DIR}}/research.md
-
-1. **Relevant files** — every file to read or modify, with brief descriptions
-2. **Existing patterns** — how similar features are implemented in this codebase
-3. **Dependencies** — libraries, utilities, shared code that are relevant
-4. **Potential impact areas** — what else might break (tests, types, imports, configs)
-5. **Existing test coverage** — which test files cover affected modules, what gaps exist. Run the project's test command to confirm the suite passes.
-6. **Edge cases and constraints** — anything tricky
-7. **Reference implementations** — similar features already built

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

@@ -1,27 +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:** Do **NOT** implement. Your **ONLY** deliverable is @{{ISSUE_DIR}}/plan.md.
-
-Read actual source files before suggesting changes. If the issue is infeasible, explain why and propose the closest feasible alternative.
-
-The code lives primarily at `{{SCOPE_PATH}}/`.
-
-## Write @{{ISSUE_DIR}}/plan.md
-
-1. **Summary** — what we're building and why (1-2 paragraphs)
-2. **Approach** — the high-level technical approach
-3. **Architectural decisions** — significant choices and why
-4. **Key code snippets** — concrete examples (function signatures, schemas, etc.)
-5. **Scope boundaries** — what is explicitly out of scope
-6. **Risks** — anything that needs special attention
-7. **Test strategy** — use red/green TDD: for each testable behavior, write the test first (red), then implement to make it pass (green). List which test files to write/update and what each test asserts. Reference specific test files from the research. Prefer real implementations over mocks — only mock at external boundaries (network, filesystem, third-party APIs). Do not write tests for things the type system or compiler already enforces.
-8. **Alternative approaches** — other valid solutions, why the chosen approach was preferred. For PR reviewers only.
-
-**Design principles:**
-
-- If the plan touches an area with a known bug, address it now.
-- Reuse existing abstractions — don't create parallel primitives.
-
-Keep under 500 lines. Focus on decisions, not repeating the research.

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

@@ -1,15 +0,0 @@
-You are a senior developer revising a plan based on reviewer feedback.
-
-Read the plan in @{{ISSUE_DIR}}/plan.md and annotations in @{{ISSUE_DIR}}/plan-annotations.md. The issue is in @{{ISSUE_DIR}}/initial-ramblings.md and research in @{{ISSUE_DIR}}/research.md.
-
-**CRITICAL:** Do **NOT** implement. Deliverables: (1) updated @{{ISSUE_DIR}}/plan.md, (2) @{{ISSUE_DIR}}/plan-annotations-addressed.md.
-
-The code lives primarily at `{{SCOPE_PATH}}/`.
-
-## Instructions
-
-- Address every annotation — update the plan to incorporate feedback.
-- Questions → answer in the plan. Suggested approaches → evaluate and update. Missing info → add it.
-- If annotations contradict each other, choose the approach that best fits codebase patterns and document why.
-- Keep the same structure and formatting.
-- Write @{{ISSUE_DIR}}/plan-annotations-addressed.md listing each annotation and how it was addressed (one line per annotation).

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

@@ -1,35 +0,0 @@
-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:** Do **NOT** implement. Your **ONLY** deliverable is @{{ISSUE_DIR}}/plan-implementation.md.
-
-The code lives primarily at `{{SCOPE_PATH}}/`.
-
-## Write @{{ISSUE_DIR}}/plan-implementation.md
-
-- **Ordered markdown checkboxes** (`- [ ]` per task), small enough to implement in one focused session
-- Prefer real implementations over mocks — only mock at external boundaries (network, filesystem, third-party APIs)
-- Do not write tests for things the type system or compiler already enforces
-- Each task must follow **red/green TDD** structure:
-  - **Files** — specific file paths to modify
-  - **Changes** — concrete description (not vague like "update the component")
-  - **Red** — write this test first, assert this behavior, run tests and confirm it **fails**
-  - **Green** — implement the change, run tests and confirm it **passes**
-  - **Acceptance** — how to verify the task is done
-- Order tasks so each builds on the previous (no forward dependencies)
-- Include setup tasks (new files, dependencies) as needed
-- Final task: "Run the project's type-check, test, and lint commands. Confirm zero errors."
-
-Example:
-
-```
-- [ ] **Task 1: Add config schema**
-  - Files: `src/lib/feature/config.ts`, `src/lib/feature/config.test.ts`
-  - Changes: Define config schema with validation, export inferred type
-  - Red: Write test asserting schema validates correct input and rejects invalid input — confirm it fails
-  - Green: Implement the schema — confirm test passes
-  - Acceptance: All tests pass, schema correctly validates/rejects
-```
-
-Be specific enough that a developer can follow without re-reading the research or plan.

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

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

package/src/lib/auto-claude/steps/plan-annotations.ts

@@ -1,54 +0,0 @@
-import { renameSync } from "node:fs";
-import { join } from "node:path";
-
-import consola from "consola";
-
-import { getConfig } from "../config.js";
-import { ARTIFACTS, STEP_LABELS, TEMPLATES } from "../prompt-templates/index.js";
-import {
-  buildTokens,
-  commitArtifacts,
-  fileExists,
-  log,
-  logStep,
-  resolveTemplate,
-  runClaude,
-} from "../utils.js";
-import type { IssueContext } from "../utils.js";
-
-export async function stepPlanAnnotations(ctx: IssueContext): Promise<boolean> {
-  const annotationsPath = join(ctx.issueDir, ARTIFACTS.planAnnotations);
-  const addressedPath = join(ctx.issueDir, ARTIFACTS.planAnnotationsAddressed);
-
-  if (!fileExists(annotationsPath)) {
-    return true;
-  }
-
-  if (fileExists(addressedPath)) {
-    logStep(STEP_LABELS.planAnnotations, ctx, true);
-    return true;
-  }
-
-  logStep(STEP_LABELS.planAnnotations, ctx);
-  log("Found plan-annotations.md — addressing reviewer notes");
-
-  const tokens = buildTokens(ctx);
-  const promptFile = resolveTemplate(TEMPLATES.planAnnotations, tokens, ctx.issueDir);
-
-  const result = await runClaude({
-    promptFile,
-    permissionMode: "acceptEdits",
-    maxTurns: getConfig().maxTurns,
-  });
-
-  if (result.is_error) {
-    consola.error(`Plan-Annotations step failed: ${result.result}`);
-    return false;
-  }
-
-  renameSync(annotationsPath, addressedPath);
-  log("Annotations addressed — renamed to plan-annotations-addressed.md");
-
-  await commitArtifacts(ctx, `chore(auto-claude): plan annotations for ${ctx.repo}#${ctx.number}`);
-  return true;
-}

package/src/lib/auto-claude/steps/plan-implementation.ts

@@ -1,14 +0,0 @@
-import { join } from "node:path";
-
-import { ARTIFACTS, STEP_LABELS, TEMPLATES } from "../prompt-templates/index.js";
-import { runStepWithArtifact } from "../utils.js";
-import type { IssueContext } from "../utils.js";
-
-export async function stepPlanImplementation(ctx: IssueContext): Promise<boolean> {
-  return runStepWithArtifact({
-    stepName: STEP_LABELS.planImplementation,
-    ctx,
-    artifactPath: join(ctx.issueDir, ARTIFACTS.planImplementation),
-    templateName: TEMPLATES.planImplementation,
-  });
-}

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

@@ -1,14 +0,0 @@
-import { join } from "node:path";
-
-import { ARTIFACTS, STEP_LABELS, TEMPLATES } from "../prompt-templates/index.js";
-import { runStepWithArtifact } from "../utils.js";
-import type { IssueContext } from "../utils.js";
-
-export async function stepPlan(ctx: IssueContext): Promise<boolean> {
-  return runStepWithArtifact({
-    stepName: STEP_LABELS.plan,
-    ctx,
-    artifactPath: join(ctx.issueDir, ARTIFACTS.plan),
-    templateName: TEMPLATES.plan,
-  });
-}

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

@@ -1,114 +0,0 @@
-import { rmSync } from "node:fs";
-import { join } from "node:path";
-
-import consola from "consola";
-
-import { getConfig } from "../config.js";
-import { ARTIFACTS, STEP_LABELS, TEMPLATES } from "../prompt-templates/index.js";
-import {
-  buildTokens,
-  commitArtifacts,
-  execSafe,
-  fileExists,
-  git,
-  log,
-  logStep,
-  resolveTemplate,
-  runClaude,
-} from "../utils.js";
-import type { IssueContext } from "../utils.js";
-
-export async function stepRefresh(ctx: IssueContext): Promise<boolean> {
-  logStep(STEP_LABELS.refresh, ctx);
-  const { mainBranch, remote } = getConfig();
-
-  const branchList = await git(["branch", "--list", ctx.branch]);
-  if (!branchList.includes(ctx.branch.split("/").pop()!)) {
-    try {
-      await git(["fetch", remote, ctx.branch]);
-      await git(["checkout", ctx.branch]);
-    } catch {
-      log(`Branch ${ctx.branch} does not exist locally or remotely.`);
-      return false;
-    }
-  }
-
-  await git(["checkout", mainBranch]);
-  await git(["pull", remote, mainBranch]);
-  await git(["checkout", ctx.branch]);
-
-  if (await isBranchUpToDate(mainBranch)) {
-    log(`Branch is already up-to-date with ${mainBranch}.`);
-  } else {
-    await rebaseOrMerge(mainBranch);
-  }
-
-  const tokens = buildTokens(ctx);
-  const promptFile = resolveTemplate(TEMPLATES.refresh, tokens, ctx.issueDir);
-  const result = await runClaude({
-    promptFile,
-    permissionMode: "acceptEdits",
-    maxTurns: getConfig().maxTurns,
-  });
-
-  if (result.is_error) {
-    consola.error(`Refresh step failed: ${result.result}`);
-    await git(["checkout", mainBranch]).catch(() => {});
-    return false;
-  }
-
-  await commitArtifacts(ctx, `chore(auto-claude): refresh for ${ctx.repo}#${ctx.number}`);
-  await invalidateStaleArtifacts(ctx);
-
-  await git(["push", "--force-with-lease", "-u", remote, ctx.branch]);
-  await git(["checkout", mainBranch]).catch(() => {});
-
-  return true;
-}
-
-async function isBranchUpToDate(mainBranch: string): Promise<boolean> {
-  try {
-    await git(["merge-base", "--is-ancestor", mainBranch, "HEAD"]);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function rebaseOrMerge(mainBranch: string): Promise<void> {
-  try {
-    await git(["rebase", mainBranch]);
-  } catch {
-    await git(["rebase", "--abort"]).catch(() => {});
-    try {
-      await git(["merge", mainBranch, "--no-edit"]);
-    } catch {
-      const conflicts = await execSafe("git", ["diff", "--name-only", "--diff-filter=U"]);
-      if (conflicts.stdout.length > 0) {
-        await git(["merge", "--abort"]);
-        throw new Error(`Merge conflicts detected in: ${conflicts.stdout}`);
-      }
-      await git(["add", "."]);
-      await git(["commit", "--no-edit"]);
-    }
-  }
-}
-
-async function invalidateStaleArtifacts(ctx: IssueContext): Promise<void> {
-  const paths = [
-    join(ctx.issueDir, ARTIFACTS.review),
-    join(ctx.issueDir, ARTIFACTS.completedSummary),
-  ];
-
-  const removed = paths.filter((p) => {
-    if (fileExists(p)) {
-      rmSync(p);
-      return true;
-    }
-    return false;
-  });
-
-  if (removed.length > 0) {
-    await commitArtifacts(ctx, "chore(auto-claude): invalidate stale artifacts after refresh");
-  }
-}

package/src/lib/auto-claude/steps/remove-label.ts

@@ -1,22 +0,0 @@
-import { getConfig } from "../config.js";
-import { STEP_LABELS } from "../prompt-templates/index.js";
-import { ghRaw, log, logStep } from "../utils.js";
-import type { IssueContext } from "../utils.js";
-
-export async function stepRemoveLabel(ctx: IssueContext): Promise<boolean> {
-  logStep(STEP_LABELS.removeLabel, ctx);
-
-  const cfg = getConfig();
-  await ghRaw([
-    "issue",
-    "edit",
-    String(ctx.number),
-    "--repo",
-    ctx.repo,
-    "--remove-label",
-    cfg.triggerLabel,
-  ]);
-
-  log(`Removed "${cfg.triggerLabel}" label from ${ctx.repo}#${ctx.number}`);
-  return true;
-}

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

@@ -1,21 +0,0 @@
-import { join } from "node:path";
-
-import { ARTIFACTS, STEP_LABELS, TEMPLATES } from "../prompt-templates/index.js";
-import { ensureBranch, fileExists, readFile, runStepWithArtifact } from "../utils.js";
-import type { IssueContext } from "../utils.js";
-
-function isValidResearch(path: string): boolean {
-  return fileExists(path) && readFile(path).length > 200;
-}
-
-export async function stepResearch(ctx: IssueContext): Promise<boolean> {
-  await ensureBranch(ctx.branch);
-
-  return runStepWithArtifact({
-    stepName: STEP_LABELS.research,
-    ctx,
-    artifactPath: join(ctx.issueDir, ARTIFACTS.research),
-    templateName: TEMPLATES.research,
-    artifactValidator: isValidResearch,
-  });
-}

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

@@ -1,14 +0,0 @@
-import { join } from "node:path";
-
-import { ARTIFACTS, STEP_LABELS, TEMPLATES } from "../prompt-templates/index.js";
-import { runStepWithArtifact } from "../utils.js";
-import type { IssueContext } from "../utils.js";
-
-export async function stepReview(ctx: IssueContext): Promise<boolean> {
-  return runStepWithArtifact({
-    stepName: STEP_LABELS.review,
-    ctx,
-    artifactPath: join(ctx.issueDir, ARTIFACTS.review),
-    templateName: TEMPLATES.review,
-  });
-}