@towles/tool 0.0.59 → 0.0.60

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@towles/tool",
-  "version": "0.0.59",
+  "version": "0.0.60",
   "description": "CLI tool with auto-claude pipeline, developer tools, and journaling via markdown.",
   "keywords": [
     "auto-claude",

package/src/commands/gh/branch.test.ts

@@ -1,124 +1,123 @@
 import { describe, expect, it } from "vitest";
+import stripAnsi from "strip-ansi";
 import type { Issue } from "../../utils/git/gh-cli-wrapper";
-import GhBranch from "./branch";
+import { buildIssueChoices, computeColumnLayout } from "./branch";
 
-const createBranchNameFromIssue = GhBranch.createBranchNameFromIssue;
+const issues: Issue[] = [
+  {
+    number: 4,
+    title: "Short bug",
+    state: "open",
+    labels: [{ name: "bug", color: "d73a4a" }],
+  },
+  {
+    number: 123,
+    title: "Add authentication flow with OAuth",
+    state: "open",
+    labels: [
+      { name: "enhancement", color: "a2eeef" },
+      { name: "priority", color: "ff0000" },
+    ],
+  },
+  {
+    number: 7,
+    title: "Docs update",
+    state: "open",
+    labels: [],
+  },
+];
 
-describe("gh-branch", () => {
-  describe("createBranchNameFromIssue", () => {
-    it("creates branch name from issue with basic title", () => {
-      const issue: Issue = {
-        number: 4,
-        title: "Long Issue Title - with a lot of words     and stuff ",
-        state: "open",
-        labels: [],
-      };
-      const branchName = createBranchNameFromIssue(issue);
-      expect(branchName).toBe("feature/4-long-issue-title-with-a-lot-of-words-and-stuff");
-    });
+describe("computeColumnLayout", () => {
+  it("computes longestNumber from widest issue number", () => {
+    const layout = computeColumnLayout(issues, 100);
+    // "123" is 3 chars
+    expect(layout.longestNumber).toBe(3);
+  });
+
+  it("computes longestLabels from widest joined label string", () => {
+    const layout = computeColumnLayout(issues, 100);
+    // "enhancement, priority" is 21 chars
+    expect(layout.longestLabels).toBe("enhancement, priority".length);
+  });
 
-    it("handles special characters in title", () => {
-      const issue: Issue = {
-        number: 123,
-        title: "Fix bug: @user reported $100 issue!",
-        state: "open",
-        labels: [],
-      };
-      const branchName = createBranchNameFromIssue(issue);
-      expect(branchName).toBe("feature/123-fix-bug-user-reported-100-issue");
-    });
+  it("caps line width at 130", () => {
+    const narrow = computeColumnLayout(issues, 80);
+    const wide = computeColumnLayout(issues, 200);
+    // descriptionLength = min(cols, 130) - longestNumber - longestLabels - 15
+    expect(narrow.descriptionLength).toBe(80 - 3 - 21 - 15);
+    expect(wide.descriptionLength).toBe(130 - 3 - 21 - 15);
+  });
 
-    it("handles title with only numbers", () => {
-      const issue: Issue = {
-        number: 42,
-        title: "123 456",
-        state: "open",
-        labels: [],
-      };
-      const branchName = createBranchNameFromIssue(issue);
-      expect(branchName).toBe("feature/42-123-456");
-    });
+  it("handles single issue", () => {
+    const single: Issue[] = [{ number: 1, title: "t", state: "open", labels: [] }];
+    const layout = computeColumnLayout(single, 80);
+    expect(layout.longestNumber).toBe(1);
+    expect(layout.longestLabels).toBe(0);
+    expect(layout.descriptionLength).toBe(80 - 1 - 0 - 15);
+  });
+
+  it("handles issues with no labels", () => {
+    const noLabels: Issue[] = [
+      { number: 42, title: "No labels here", state: "open", labels: [] },
+      { number: 100, title: "Also no labels", state: "open", labels: [] },
+    ];
+    const layout = computeColumnLayout(noLabels, 100);
+    expect(layout.longestLabels).toBe(0);
+    expect(layout.longestNumber).toBe(3);
+  });
+});
 
-    it("trims trailing dashes", () => {
-      const issue: Issue = {
-        number: 7,
-        title: "Update docs ---",
-        state: "open",
-        labels: [],
-      };
-      const branchName = createBranchNameFromIssue(issue);
-      expect(branchName).toBe("feature/7-update-docs");
-    });
+describe("buildIssueChoices", () => {
+  const layout = computeColumnLayout(issues, 100);
 
-    it("handles unicode characters", () => {
-      const issue: Issue = {
-        number: 99,
-        title: "Fix für Übersetzung",
-        state: "open",
-        labels: [],
-      };
-      const branchName = createBranchNameFromIssue(issue);
-      expect(branchName).toBe("feature/99-fix-f-r-bersetzung");
-    });
+  it("returns one choice per issue plus a Cancel option", () => {
+    const choices = buildIssueChoices(issues, layout);
+    expect(choices).toHaveLength(issues.length + 1);
+  });
 
-    it("handles empty-ish title", () => {
-      const issue: Issue = {
-        number: 1,
-        title: "   ",
-        state: "open",
-        labels: [],
-      };
-      const branchName = createBranchNameFromIssue(issue);
-      expect(branchName).toBe("feature/1-");
-    });
+  it("last choice is Cancel", () => {
+    const choices = buildIssueChoices(issues, layout);
+    const last = choices[choices.length - 1];
+    expect(last.title).toBe("Cancel");
+    expect(last.value).toBe("cancel");
+  });
 
-    it("handles title with underscores", () => {
-      const issue: Issue = {
-        number: 50,
-        title: "snake_case_title",
-        state: "open",
-        labels: [],
-      };
-      const branchName = createBranchNameFromIssue(issue);
-      expect(branchName).toBe("feature/50-snake_case_title");
-    });
+  it("uses issue number as title and value", () => {
+    const choices = buildIssueChoices(issues, layout);
+    expect(choices[0].title).toBe("4");
+    expect(choices[0].value).toBe(4);
+    expect(choices[1].title).toBe("123");
+    expect(choices[1].value).toBe(123);
+  });
 
-    it("handles very long titles", () => {
-      const issue: Issue = {
-        number: 200,
-        title: "This is a very long issue title that goes on and on with many words",
-        state: "open",
-        labels: [],
-      };
-      const branchName = createBranchNameFromIssue(issue);
-      expect(branchName).toBe(
-        "feature/200-this-is-a-very-long-issue-title-that-goes-on-and-on-with-many-words",
-      );
-    });
+  it("includes issue title text in description", () => {
+    const choices = buildIssueChoices(issues, layout);
+    const desc = stripAnsi(choices[0].description!);
+    expect(desc).toContain("Short bug");
+  });
 
-    it("collapses multiple consecutive dashes", () => {
-      const issue: Issue = {
-        number: 15,
-        title: "Fix   multiple    spaces",
-        state: "open",
-        labels: [],
-      };
-      const branchName = createBranchNameFromIssue(issue);
-      expect(branchName).toBe("feature/15-fix-multiple-spaces");
-    });
+  it("includes label names in description", () => {
+    const choices = buildIssueChoices(issues, layout);
+    const desc = stripAnsi(choices[1].description!);
+    expect(desc).toContain("enhancement");
+    expect(desc).toContain("priority");
+  });
 
-    it("handles title with brackets and parentheses", () => {
-      const issue: Issue = {
-        number: 33,
-        title: "[Bug] Fix (critical) issue",
-        state: "open",
-        labels: [],
-      };
-      const branchName = createBranchNameFromIssue(issue);
-      expect(branchName).toBe("feature/33--bug-fix-critical-issue");
-    });
+  it("handles issues with no labels", () => {
+    const choices = buildIssueChoices(issues, layout);
+    // Issue #7 has no labels — description should still contain the title
+    const desc = stripAnsi(choices[2].description!);
+    expect(desc).toContain("Docs update");
   });
 
-  // TODO: Integration tests for githubBranchCommand require module mocking
-  // which works differently in bun:test vs vitest
+  it("works with empty issue list", () => {
+    const emptyLayout = computeColumnLayout(
+      [{ number: 0, title: "", state: "open", labels: [] }],
+      80,
+    );
+    const choices = buildIssueChoices([], emptyLayout);
+    // Only the Cancel choice
+    expect(choices).toHaveLength(1);
+    expect(choices[0].value).toBe("cancel");
+  });
 });

package/src/commands/gh/branch.ts

@@ -6,11 +6,46 @@ import { Fzf } from "fzf";
 import consola from "consola";
 
 import { BaseCommand } from "../base.js";
-import { getIssues, isGithubCliInstalled } from "../../utils/git/gh-cli-wrapper.js";
 import type { Issue } from "../../utils/git/gh-cli-wrapper.js";
+import { getIssues, isGithubCliInstalled } from "../../utils/git/gh-cli-wrapper.js";
 import { createBranch } from "../../utils/git/git-wrapper.js";
+import { createBranchNameFromIssue } from "../../utils/git/branch-name.js";
 import { getTerminalColumns, limitText, printWithHexColor } from "../../utils/render.js";
 
+export interface ColumnLayout {
+  longestNumber: number;
+  longestLabels: number;
+  descriptionLength: number;
+}
+
+export function computeColumnLayout(issues: Issue[], terminalColumns: number): ColumnLayout {
+  const longestNumber = Math.max(...issues.map((i) => i.number.toString().length));
+  const longestLabels = Math.max(
+    ...issues.map((i) => i.labels.map((x) => x.name).join(", ").length),
+  );
+  const lineMaxLength = Math.min(terminalColumns, 130);
+  const descriptionLength = lineMaxLength - longestNumber - longestLabels - 15;
+
+  return { longestNumber, longestLabels, descriptionLength };
+}
+
+export function buildIssueChoices(issues: Issue[], layout: ColumnLayout): Choice[] {
+  const choices: Choice[] = issues.map((i) => {
+    const labelText = i.labels
+      .map((l) => printWithHexColor({ msg: l.name, hex: l.color }))
+      .join(", ");
+    const labelTextNoColor = i.labels.map((l) => l.name).join(", ");
+    const labelStartpad = layout.longestLabels - labelTextNoColor.length;
+    return {
+      title: i.number.toString(),
+      value: i.number,
+      description: `${limitText(i.title, layout.descriptionLength).padEnd(layout.descriptionLength)} ${"".padStart(labelStartpad)}${labelText}`,
+    } as Choice;
+  });
+  choices.push({ title: "Cancel", value: "cancel" });
+  return choices;
+}
+
 /**
  * Create a git branch from a GitHub issue
  */
@@ -55,29 +90,8 @@ export default class GhBranch extends BaseCommand {
       consola.log(colors.green(`${currentIssues.length} Issues found assigned to you`));
     }
 
-    // Format table with nice labels
-    let lineMaxLength = getTerminalColumns();
-    const longestNumber = Math.max(...currentIssues.map((i) => i.number.toString().length));
-    const longestLabels = Math.max(
-      ...currentIssues.map((i) => i.labels.map((x) => x.name).join(", ").length),
-    );
-
-    lineMaxLength = lineMaxLength > 130 ? 130 : lineMaxLength;
-    const descriptionLength = lineMaxLength - longestNumber - longestLabels - 15;
-
-    const choices: Choice[] = currentIssues.map((i) => {
-      const labelText = i.labels
-        .map((l) => printWithHexColor({ msg: l.name, hex: l.color }))
-        .join(", ");
-      const labelTextNoColor = i.labels.map((l) => l.name).join(", ");
-      const labelStartpad = longestLabels - labelTextNoColor.length;
-      return {
-        title: i.number.toString(),
-        value: i.number,
-        description: `${limitText(i.title, descriptionLength).padEnd(descriptionLength)} ${"".padStart(labelStartpad)}${labelText}`,
-      } as Choice;
-    });
-    choices.push({ title: "Cancel", value: "cancel" });
+    const layout = computeColumnLayout(currentIssues, getTerminalColumns());
+    const choices = buildIssueChoices(currentIssues, layout);
 
     const fzf = new Fzf(choices, {
       selector: (item) => `${item.value} ${item.description}`,
@@ -115,21 +129,10 @@ export default class GhBranch extends BaseCommand {
         `Selected issue ${colors.green(selectedIssue.number)} - ${colors.green(selectedIssue.title)}`,
       );
 
-      const branchName = GhBranch.createBranchNameFromIssue(selectedIssue);
+      const branchName = createBranchNameFromIssue(selectedIssue);
       createBranch({ branchName });
     } catch {
       this.exit(1);
     }
   }
-
-  static createBranchNameFromIssue(selectedIssue: Issue): string {
-    let slug = selectedIssue.title.toLowerCase();
-    slug = slug.trim();
-    slug = slug.replaceAll(" ", "-");
-    slug = slug.replace(/[^0-9a-zA-Z_-]/g, "-");
-    slug = slug.replace(/-+/g, "-");
-    slug = slug.replace(/-+$/, "");
-
-    return `feature/${selectedIssue.number}-${slug}`;
-  }
 }

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

@@ -0,0 +1,195 @@
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import consola from "consola";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { initConfig } from "./config";
+import { ARTIFACTS } from "./prompt-templates/index";
+import {
+  buildTestContext,
+  createTestRepoWithRemote,
+  errorClaudeJson,
+  successClaudeJson,
+} from "./test-helpers";
+import type { TestRepo } from "./test-helpers";
+import type { IssueContext } from "./utils";
+
+consola.level = -999;
+
+// ── Mock tinyexec: intercept "claude" and "gh" calls, pass through git ──
+
+let mockClaudeImpl: ((args: string[]) => Promise<{ stdout: string; exitCode: number }>) | null =
+  null;
+let mockGhImpl: ((args: string[]) => Promise<{ stdout: string; exitCode: number }>) | null = null;
+
+vi.mock("tinyexec", async (importOriginal) => {
+  const original = await importOriginal<typeof import("tinyexec")>();
+  return {
+    ...original,
+    x: vi.fn(
+      async (
+        cmd: string,
+        args: string[],
+        opts?: Record<string, unknown>,
+      ): Promise<{ stdout: string; exitCode: number }> => {
+        if (cmd === "claude" && mockClaudeImpl) {
+          return mockClaudeImpl(args);
+        }
+        if (cmd === "claude") {
+          throw new Error("Unexpected claude call -- set mockClaudeImpl");
+        }
+        if (cmd === "gh" && mockGhImpl) {
+          return mockGhImpl(args);
+        }
+        if (cmd === "gh") {
+          throw new Error("Unexpected gh call -- set mockGhImpl");
+        }
+        return original.x(cmd, args, opts as never) as unknown as Promise<{
+          stdout: string;
+          exitCode: number;
+        }>;
+      },
+    ),
+  };
+});
+
+describe("runPipeline", () => {
+  let originalCwd: string;
+  let repo: TestRepo;
+  let ctx: IssueContext;
+
+  beforeEach(async () => {
+    originalCwd = process.cwd();
+    repo = createTestRepoWithRemote();
+    process.chdir(repo.dir);
+    await initConfig({
+      repo: "test/repo",
+      mainBranch: "main",
+      maxImplementIterations: 2,
+    });
+    ctx = buildTestContext(repo.dir);
+    mockClaudeImpl = null;
+    mockGhImpl = null;
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    repo.cleanup();
+  });
+
+  it("writes initial-ramblings.md on first run", async () => {
+    const { runPipeline } = await import("./pipeline");
+
+    mockClaudeImpl = async () => ({ stdout: errorClaudeJson(), exitCode: 0 });
+
+    await runPipeline(ctx);
+
+    const ramblingsPath = join(ctx.issueDir, ARTIFACTS.initialRamblings);
+    expect(existsSync(ramblingsPath)).toBe(true);
+
+    const content = readFileSync(ramblingsPath, "utf-8");
+    expect(content).toContain(ctx.title);
+    expect(content).toContain(`${ctx.repo}#${ctx.number}`);
+  });
+
+  it("skips writing initial-ramblings.md if already present", async () => {
+    const { runPipeline } = await import("./pipeline");
+
+    mkdirSync(ctx.issueDir, { recursive: true });
+    const ramblingsPath = join(ctx.issueDir, ARTIFACTS.initialRamblings);
+    writeFileSync(ramblingsPath, "# Existing ramblings");
+
+    mockClaudeImpl = async () => ({ stdout: errorClaudeJson(), exitCode: 0 });
+
+    await runPipeline(ctx);
+
+    const content = readFileSync(ramblingsPath, "utf-8");
+    expect(content).toBe("# Existing ramblings");
+  });
+
+  it("stops after --until step", async () => {
+    const { runPipeline } = await import("./pipeline");
+
+    let claudeCallCount = 0;
+    const researchPath = join(ctx.issueDir, ARTIFACTS.research);
+
+    mockClaudeImpl = async () => {
+      claudeCallCount++;
+      mkdirSync(ctx.issueDir, { recursive: true });
+      writeFileSync(researchPath, "x".repeat(250));
+      return { stdout: successClaudeJson(), exitCode: 0 };
+    };
+
+    await runPipeline(ctx, "research");
+
+    expect(claudeCallCount).toBe(1);
+  });
+
+  it("stops and checks out main on step failure", async () => {
+    const { runPipeline } = await import("./pipeline");
+
+    mockClaudeImpl = async () => ({ stdout: errorClaudeJson(), exitCode: 0 });
+
+    await runPipeline(ctx);
+
+    const currentBranch = execSync("git branch --show-current", {
+      cwd: repo.dir,
+      encoding: "utf-8",
+    }).trim();
+    expect(currentBranch).toBe("main");
+  });
+
+  it("runs all steps in order when all succeed", async () => {
+    const { runPipeline } = await import("./pipeline");
+
+    let claudeCallCount = 0;
+    mockClaudeImpl = async () => {
+      claudeCallCount++;
+      mkdirSync(ctx.issueDir, { recursive: true });
+
+      switch (claudeCallCount) {
+        case 1:
+          writeFileSync(join(ctx.issueDir, ARTIFACTS.research), "x".repeat(250));
+          break;
+        case 2:
+          writeFileSync(join(ctx.issueDir, ARTIFACTS.plan), "# Plan");
+          break;
+        case 3:
+          writeFileSync(join(ctx.issueDir, ARTIFACTS.planImplementation), "# Impl Plan");
+          break;
+        case 4:
+          writeFileSync(join(ctx.issueDir, ARTIFACTS.completedSummary), "# Done");
+          break;
+        case 5:
+          writeFileSync(join(ctx.issueDir, ARTIFACTS.review), "# Review\nLooks good.");
+          break;
+      }
+      return { stdout: successClaudeJson(), exitCode: 0 };
+    };
+
+    let ghCallCount = 0;
+    mockGhImpl = async (args: string[]) => {
+      ghCallCount++;
+      if (args[0] === "pr" && args[1] === "list") {
+        return { stdout: "[]", exitCode: 0 };
+      }
+      if (args[0] === "pr" && args[1] === "create") {
+        return { stdout: "https://github.com/test/repo/pull/1", exitCode: 0 };
+      }
+      return { stdout: "", exitCode: 0 };
+    };
+
+    await runPipeline(ctx);
+
+    const prUrlPath = join(ctx.issueDir, ARTIFACTS.prUrl);
+    if (existsSync(prUrlPath)) {
+      const prUrl = readFileSync(prUrlPath, "utf-8");
+      expect(prUrl).toContain("github.com");
+    }
+
+    expect(claudeCallCount).toBe(5);
+    expect(ghCallCount).toBeGreaterThanOrEqual(2);
+  });
+});

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

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

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

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

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