harness-auto-docs 0.1.0

package/docs/superpowers/plans/2026-04-03-harness-engineering-auto-docs.md

@@ -0,0 +1,1863 @@
+# Harness Engineering Auto Docs Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build and publish an npm CLI package (`harness-engineering-auto-docs`) that runs via `npx`, extracts the git diff between two tags, generates Harness Engineering-style documentation using a configurable AI model, and opens a PR.
+
+**Architecture:** Three independent layers — `core/` (diff, relevance, generation, file writing), `ai/` (Anthropic + OpenAI providers behind a shared interface), and `providers/` (GitHub PR creation; GitLab stub). The CLI (`cli.ts`) wires them together: write docs to disk → git commit + push → platform API creates PR.
+
+**Tech Stack:** TypeScript 5, Node.js 18+, `@anthropic-ai/sdk`, `openai`, `@octokit/rest`, `tsx` (CLI runner), Vitest (tests)
+
+---
+
+## File Structure
+
+```
+harness-engineering-auto-docs/
+├── package.json
+├── tsconfig.json
+├── vitest.config.ts
+├── src/
+│   ├── cli.ts                    # Entry point: orchestrates full pipeline
+│   ├── ai/
+│   │   ├── interface.ts          # AIProvider interface
+│   │   ├── anthropic.ts          # Claude implementation
+│   │   └── openai.ts             # GPT implementation
+│   ├── core/
+│   │   ├── diff.ts               # git diff extraction + file grouping
+│   │   ├── relevance.ts          # diff → target document selection
+│   │   ├── generator.ts          # AI prompts + concurrent doc generation
+│   │   └── writer.ts             # append-to / create-file utilities
+│   └── providers/
+│       ├── interface.ts          # PlatformProvider interface
+│       ├── github.ts             # GitHub PR creation via Octokit
+│       └── gitlab.ts             # GitLab stub (not yet implemented)
+├── tests/
+│   ├── fixtures/
+│   │   ├── diff-small.txt
+│   │   ├── diff-schema.txt
+│   │   └── diff-frontend.txt
+│   ├── core/
+│   │   ├── diff.test.ts
+│   │   ├── relevance.test.ts
+│   │   ├── writer.test.ts
+│   │   └── generator.test.ts
+│   ├── providers/
+│   │   └── github.test.ts
+│   └── integration/
+│       └── generate.test.ts
+└── examples/
+    └── github-workflow.yml
+```
+
+---
+
+## Task 1: Project Scaffolding
+
+**Files:**
+- Create: `package.json`
+- Create: `tsconfig.json`
+- Create: `vitest.config.ts`
+
+- [ ] **Step 1: Create package.json**
+
+```json
+{
+  "name": "harness-engineering-auto-docs",
+  "version": "0.1.0",
+  "description": "Auto-generate Harness Engineering docs on git tag",
+  "type": "module",
+  "bin": {
+    "harness-engineering-auto-docs": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@octokit/rest": "^21.0.0",
+    "openai": "^4.85.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}
+```
+
+- [ ] **Step 2: Create tsconfig.json**
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}
+```
+
+- [ ] **Step 3: Create vitest.config.ts**
+
+```typescript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+  },
+});
+```
+
+- [ ] **Step 4: Install dependencies**
+
+```bash
+npm install
+```
+
+Expected: `node_modules/` created, no errors.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add package.json tsconfig.json vitest.config.ts
+git commit -m "chore: project scaffolding"
+```
+
+---
+
+## Task 2: AI Provider Interface + Anthropic
+
+**Files:**
+- Create: `src/ai/interface.ts`
+- Create: `src/ai/anthropic.ts`
+- Create: `tests/core/anthropic.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```typescript
+// tests/core/anthropic.test.ts
+import { describe, it, expect, vi } from 'vitest';
+import { AnthropicProvider } from '../../src/ai/anthropic.js';
+
+vi.mock('@anthropic-ai/sdk', () => ({
+  default: vi.fn().mockImplementation(() => ({
+    messages: {
+      create: vi.fn().mockResolvedValue({
+        content: [{ type: 'text', text: 'generated content' }],
+      }),
+    },
+  })),
+}));
+
+describe('AnthropicProvider', () => {
+  it('returns text content from the API response', async () => {
+    const provider = new AnthropicProvider('test-key', 'claude-sonnet-4-6');
+    const result = await provider.generate('write docs for this diff');
+    expect(result).toBe('generated content');
+  });
+
+  it('throws if response content is not text', async () => {
+    const { default: Anthropic } = await import('@anthropic-ai/sdk');
+    vi.mocked(Anthropic).mockImplementationOnce(() => ({
+      messages: {
+        create: vi.fn().mockResolvedValue({
+          content: [{ type: 'image', source: {} }],
+        }),
+      },
+    }) as any);
+    const provider = new AnthropicProvider('test-key', 'claude-sonnet-4-6');
+    await expect(provider.generate('prompt')).rejects.toThrow('Unexpected response type');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test -- tests/core/anthropic.test.ts
+```
+
+Expected: FAIL — `Cannot find module '../../src/ai/anthropic.js'`
+
+- [ ] **Step 3: Create src/ai/interface.ts**
+
+```typescript
+// src/ai/interface.ts
+export interface AIProvider {
+  generate(prompt: string): Promise<string>;
+}
+```
+
+- [ ] **Step 4: Create src/ai/anthropic.ts**
+
+```typescript
+// src/ai/anthropic.ts
+import Anthropic from '@anthropic-ai/sdk';
+import type { AIProvider } from './interface.js';
+
+export class AnthropicProvider implements AIProvider {
+  private client: Anthropic;
+  private model: string;
+
+  constructor(apiKey: string, model: string) {
+    this.client = new Anthropic({ apiKey });
+    this.model = model;
+  }
+
+  async generate(prompt: string): Promise<string> {
+    const message = await this.client.messages.create({
+      model: this.model,
+      max_tokens: 4096,
+      messages: [{ role: 'user', content: prompt }],
+    });
+    const content = message.content[0];
+    if (content.type !== 'text') throw new Error('Unexpected response type');
+    return content.text;
+  }
+}
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+```bash
+npm test -- tests/core/anthropic.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/ai/interface.ts src/ai/anthropic.ts tests/core/anthropic.test.ts
+git commit -m "feat: add AI provider interface and Anthropic implementation"
+```
+
+---
+
+## Task 3: OpenAI Provider
+
+**Files:**
+- Create: `src/ai/openai.ts`
+- Create: `tests/core/openai.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```typescript
+// tests/core/openai.test.ts
+import { describe, it, expect, vi } from 'vitest';
+import { OpenAIProvider } from '../../src/ai/openai.js';
+
+vi.mock('openai', () => ({
+  default: vi.fn().mockImplementation(() => ({
+    chat: {
+      completions: {
+        create: vi.fn().mockResolvedValue({
+          choices: [{ message: { content: 'gpt generated content' } }],
+        }),
+      },
+    },
+  })),
+}));
+
+describe('OpenAIProvider', () => {
+  it('returns text content from the API response', async () => {
+    const provider = new OpenAIProvider('test-key', 'gpt-4o');
+    const result = await provider.generate('write docs for this diff');
+    expect(result).toBe('gpt generated content');
+  });
+
+  it('returns empty string when message content is null', async () => {
+    const { default: OpenAI } = await import('openai');
+    vi.mocked(OpenAI).mockImplementationOnce(() => ({
+      chat: {
+        completions: {
+          create: vi.fn().mockResolvedValue({
+            choices: [{ message: { content: null } }],
+          }),
+        },
+      },
+    }) as any);
+    const provider = new OpenAIProvider('test-key', 'gpt-4o');
+    const result = await provider.generate('prompt');
+    expect(result).toBe('');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test -- tests/core/openai.test.ts
+```
+
+Expected: FAIL — `Cannot find module '../../src/ai/openai.js'`
+
+- [ ] **Step 3: Create src/ai/openai.ts**
+
+```typescript
+// src/ai/openai.ts
+import OpenAI from 'openai';
+import type { AIProvider } from './interface.js';
+
+export class OpenAIProvider implements AIProvider {
+  private client: OpenAI;
+  private model: string;
+
+  constructor(apiKey: string, model: string) {
+    this.client = new OpenAI({ apiKey });
+    this.model = model;
+  }
+
+  async generate(prompt: string): Promise<string> {
+    const completion = await this.client.chat.completions.create({
+      model: this.model,
+      messages: [{ role: 'user', content: prompt }],
+    });
+    return completion.choices[0].message.content ?? '';
+  }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npm test -- tests/core/openai.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/ai/openai.ts tests/core/openai.test.ts
+git commit -m "feat: add OpenAI provider"
+```
+
+---
+
+## Task 4: Diff Extraction
+
+**Files:**
+- Create: `src/core/diff.ts`
+- Create: `tests/fixtures/diff-small.txt`
+- Create: `tests/fixtures/diff-schema.txt`
+- Create: `tests/fixtures/diff-frontend.txt`
+- Create: `tests/core/diff.test.ts`
+
+- [ ] **Step 1: Create test fixtures**
+
+`tests/fixtures/diff-small.txt`:
+```
+diff --git a/src/auth/login.ts b/src/auth/login.ts
+index abc1234..def5678 100644
+--- a/src/auth/login.ts
++++ b/src/auth/login.ts
+@@ -1,5 +1,10 @@
++export function login(email: string, password: string) {
++  return { token: 'jwt' };
++}
+diff --git a/src/utils/helpers.ts b/src/utils/helpers.ts
+index 111aaaa..222bbbb 100644
+--- a/src/utils/helpers.ts
++++ b/src/utils/helpers.ts
+@@ -1,3 +1,6 @@
++export function sleep(ms: number) {
++  return new Promise(r => setTimeout(r, ms));
++}
+```
+
+`tests/fixtures/diff-schema.txt`:
+```
+diff --git a/migrations/001_add_users.sql b/migrations/001_add_users.sql
+new file mode 100644
+index 0000000..aabbcc
+--- /dev/null
++++ b/migrations/001_add_users.sql
+@@ -0,0 +1,5 @@
++CREATE TABLE users (
++  id UUID PRIMARY KEY,
++  email TEXT NOT NULL UNIQUE
++);
+diff --git a/src/db/schema.ts b/src/db/schema.ts
+new file mode 100644
+```
+
+`tests/fixtures/diff-frontend.txt`:
+```
+diff --git a/src/ui/Button.tsx b/src/ui/Button.tsx
+new file mode 100644
+index 0000000..aabbcc
+--- /dev/null
++++ b/src/ui/Button.tsx
+@@ -0,0 +1,8 @@
++export function Button({ label }: { label: string }) {
++  return <button>{label}</button>;
++}
+diff --git a/src/ui/styles.css b/src/ui/styles.css
+new file mode 100644
+```
+
+- [ ] **Step 2: Write the failing test**
+
+```typescript
+// tests/core/diff.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { parseChangedFiles, groupFiles } from '../../src/core/diff.js';
+
+const smallDiff = readFileSync(
+  join(import.meta.dirname, '../fixtures/diff-small.txt'), 'utf-8'
+);
+const schemaDiff = readFileSync(
+  join(import.meta.dirname, '../fixtures/diff-schema.txt'), 'utf-8'
+);
+const frontendDiff = readFileSync(
+  join(import.meta.dirname, '../fixtures/diff-frontend.txt'), 'utf-8'
+);
+
+describe('parseChangedFiles', () => {
+  it('extracts file paths from diff output', () => {
+    const files = parseChangedFiles(smallDiff);
+    expect(files).toContain('src/auth/login.ts');
+    expect(files).toContain('src/utils/helpers.ts');
+    expect(files).toHaveLength(2);
+  });
+
+  it('returns empty array for empty diff', () => {
+    expect(parseChangedFiles('')).toEqual([]);
+  });
+});
+
+describe('groupFiles', () => {
+  it('puts auth files in auth group', () => {
+    const groups = groupFiles(['src/auth/login.ts', 'src/utils/helpers.ts']);
+    expect(groups.auth).toContain('src/auth/login.ts');
+    expect(groups.auth).not.toContain('src/utils/helpers.ts');
+  });
+
+  it('puts sql files in schema group', () => {
+    const files = parseChangedFiles(schemaDiff);
+    const groups = groupFiles(files);
+    expect(groups.schema.length).toBeGreaterThan(0);
+  });
+
+  it('puts tsx files in frontend group', () => {
+    const files = parseChangedFiles(frontendDiff);
+    const groups = groupFiles(files);
+    expect(groups.frontend).toContain('src/ui/Button.tsx');
+    expect(groups.frontend).toContain('src/ui/styles.css');
+  });
+});
+```
+
+- [ ] **Step 3: Run test to verify it fails**
+
+```bash
+npm test -- tests/core/diff.test.ts
+```
+
+Expected: FAIL — `Cannot find module '../../src/core/diff.js'`
+
+- [ ] **Step 4: Create src/core/diff.ts**
+
+```typescript
+// src/core/diff.ts
+import { execSync } from 'child_process';
+
+export interface FileGroups {
+  frontend: string[];
+  schema: string[];
+  auth: string[];
+  infra: string[];
+  other: string[];
+}
+
+export interface DiffResult {
+  raw: string;
+  prevTag: string;
+  currentTag: string;
+  changedFiles: string[];
+  fileGroups: FileGroups;
+}
+
+export function extractDiff(): DiffResult {
+  const tags = execSync('git tag --sort=version:refname')
+    .toString()
+    .trim()
+    .split('\n')
+    .filter(Boolean);
+
+  if (tags.length === 0) throw new Error('No tags found in repository');
+
+  const currentTag = tags[tags.length - 1];
+  const prevTag = tags.length >= 2 ? tags[tags.length - 2] : null;
+
+  const raw = prevTag
+    ? execSync(`git diff ${prevTag} ${currentTag}`).toString()
+    : execSync(`git show ${currentTag} --format='' -p`).toString();
+
+  const changedFiles = parseChangedFiles(raw);
+  const fileGroups = groupFiles(changedFiles);
+
+  return {
+    raw,
+    prevTag: prevTag ?? '(initial)',
+    currentTag,
+    changedFiles,
+    fileGroups,
+  };
+}
+
+export function parseChangedFiles(diff: string): string[] {
+  const matches = diff.match(/^diff --git a\/.+ b\/(.+)$/gm) ?? [];
+  return matches.map(line => {
+    const match = line.match(/^diff --git a\/.+ b\/(.+)$/);
+    return match ? match[1] : '';
+  }).filter(Boolean);
+}
+
+export function groupFiles(files: string[]): FileGroups {
+  const isFrontend = (f: string) =>
+    /\.(tsx?|jsx?|css|scss|html|vue|svelte)$/.test(f) ||
+    /\b(ui|frontend|components|pages|views)\b/.test(f);
+
+  const isSchema = (f: string) =>
+    /\.sql$/.test(f) || /\b(schema|migration|migrate)\b/i.test(f);
+
+  const isAuth = (f: string) =>
+    /\b(auth|permission|security|oauth|jwt|session|token)\b/i.test(f);
+
+  const isInfra = (f: string) =>
+    /\b(infra|deploy|k8s|docker|compose|helm|terraform|service|gateway)\b/i.test(f);
+
+  return {
+    frontend: files.filter(isFrontend),
+    schema: files.filter(isSchema),
+    auth: files.filter(isAuth),
+    infra: files.filter(isInfra),
+    other: files.filter(f => !isFrontend(f) && !isSchema(f) && !isAuth(f) && !isInfra(f)),
+  };
+}
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+```bash
+npm test -- tests/core/diff.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/core/diff.ts tests/core/diff.test.ts tests/fixtures/
+git commit -m "feat: add diff extraction and file grouping"
+```
+
+---
+
+## Task 5: Relevance Judgment
+
+**Files:**
+- Create: `src/core/relevance.ts`
+- Create: `tests/core/relevance.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```typescript
+// tests/core/relevance.test.ts
+import { describe, it, expect } from 'vitest';
+import { selectTargets } from '../../src/core/relevance.js';
+import type { FileGroups } from '../../src/core/diff.js';
+
+const emptyGroups: FileGroups = {
+  frontend: [], schema: [], auth: [], infra: [], other: [],
+};
+
+describe('selectTargets', () => {
+  it('always includes core targets', () => {
+    const targets = selectTargets(emptyGroups, []);
+    expect(targets).toContain('AGENTS.md');
+    expect(targets).toContain('ARCHITECTURE.md');
+    expect(targets).toContain('DESIGN.md');
+    expect(targets).toContain('QUALITY_SCORE.md');
+    expect(targets).toContain('changelog');
+    expect(targets).toContain('design-doc');
+    expect(targets).toContain('design-doc-index');
+    expect(targets).toContain('tech-debt-tracker');
+  });
+
+  it('includes FRONTEND.md only when frontend files changed', () => {
+    const withFrontend = selectTargets(
+      { ...emptyGroups, frontend: ['src/ui/Button.tsx'] }, []
+    );
+    expect(withFrontend).toContain('FRONTEND.md');
+
+    const withoutFrontend = selectTargets(emptyGroups, []);
+    expect(withoutFrontend).not.toContain('FRONTEND.md');
+  });
+
+  it('includes SECURITY.md only when auth files changed', () => {
+    const targets = selectTargets(
+      { ...emptyGroups, auth: ['src/auth/login.ts'] }, []
+    );
+    expect(targets).toContain('SECURITY.md');
+  });
+
+  it('includes RELIABILITY.md only when infra files changed', () => {
+    const targets = selectTargets(
+      { ...emptyGroups, infra: ['infra/deploy.yaml'] }, []
+    );
+    expect(targets).toContain('RELIABILITY.md');
+  });
+
+  it('includes db-schema only when schema files changed', () => {
+    const targets = selectTargets(
+      { ...emptyGroups, schema: ['migrations/001.sql'] }, []
+    );
+    expect(targets).toContain('db-schema');
+  });
+
+  it('includes references when package.json changed', () => {
+    const targets = selectTargets(emptyGroups, ['package.json']);
+    expect(targets).toContain('references');
+  });
+
+  it('returns no duplicates', () => {
+    const targets = selectTargets(emptyGroups, []);
+    expect(targets.length).toBe(new Set(targets).size);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test -- tests/core/relevance.test.ts
+```
+
+Expected: FAIL — `Cannot find module '../../src/core/relevance.js'`
+
+- [ ] **Step 3: Create src/core/relevance.ts**
+
+```typescript
+// src/core/relevance.ts
+import type { FileGroups } from './diff.js';
+
+export type DocTarget =
+  | 'AGENTS.md'
+  | 'ARCHITECTURE.md'
+  | 'DESIGN.md'
+  | 'FRONTEND.md'
+  | 'SECURITY.md'
+  | 'RELIABILITY.md'
+  | 'QUALITY_SCORE.md'
+  | 'changelog'
+  | 'design-doc'
+  | 'design-doc-index'
+  | 'tech-debt-tracker'
+  | 'db-schema'
+  | 'product-specs-index'
+  | 'references';
+
+const CORE_TARGETS: DocTarget[] = [
+  'AGENTS.md',
+  'ARCHITECTURE.md',
+  'DESIGN.md',
+  'QUALITY_SCORE.md',
+  'changelog',
+  'design-doc',
+  'design-doc-index',
+  'tech-debt-tracker',
+];
+
+export function selectTargets(
+  fileGroups: FileGroups,
+  changedFiles: string[]
+): DocTarget[] {
+  const targets: DocTarget[] = [...CORE_TARGETS];
+
+  if (fileGroups.frontend.length > 0) targets.push('FRONTEND.md');
+  if (fileGroups.auth.length > 0) targets.push('SECURITY.md');
+  if (fileGroups.infra.length > 0) targets.push('RELIABILITY.md');
+  if (fileGroups.schema.length > 0) targets.push('db-schema');
+
+  const packageFiles = ['package.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'];
+  if (changedFiles.some(f => packageFiles.includes(f))) {
+    targets.push('references');
+  }
+
+  const looksLikeNewFeature = changedFiles.some(f =>
+    /\b(feature|feat|new)\b/i.test(f) || f.startsWith('src/features/')
+  );
+  if (looksLikeNewFeature) targets.push('product-specs-index');
+
+  return [...new Set(targets)];
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npm test -- tests/core/relevance.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/relevance.ts tests/core/relevance.test.ts
+git commit -m "feat: add relevance judgment for document targets"
+```
+
+---
+
+## Task 6: File Writer
+
+**Files:**
+- Create: `src/core/writer.ts`
+- Create: `tests/core/writer.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```typescript
+// tests/core/writer.test.ts
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { appendSection, createFile } from '../../src/core/writer.js';
+
+const TMP = join(import.meta.dirname, '../../tmp-writer-test');
+
+beforeEach(() => mkdirSync(TMP, { recursive: true }));
+afterEach(() => rmSync(TMP, { recursive: true, force: true }));
+
+describe('appendSection', () => {
+  it('creates file if it does not exist', () => {
+    const path = join(TMP, 'AGENTS.md');
+    appendSection(path, 'Changes in v1.1.0', 'New auth module added.');
+    expect(existsSync(path)).toBe(true);
+    const content = readFileSync(path, 'utf-8');
+    expect(content).toContain('## Changes in v1.1.0');
+    expect(content).toContain('New auth module added.');
+  });
+
+  it('appends to existing file', () => {
+    const path = join(TMP, 'ARCHITECTURE.md');
+    appendSection(path, 'Changes in v1.0.0', 'Initial architecture.');
+    appendSection(path, 'Changes in v1.1.0', 'Added caching layer.');
+    const content = readFileSync(path, 'utf-8');
+    expect(content).toContain('## Changes in v1.0.0');
+    expect(content).toContain('## Changes in v1.1.0');
+  });
+
+  it('creates missing parent directories', () => {
+    const path = join(TMP, 'docs/design-docs/index.md');
+    appendSection(path, 'v1.0.0', 'entry');
+    expect(existsSync(path)).toBe(true);
+  });
+});
+
+describe('createFile', () => {
+  it('creates a file with the given content', () => {
+    const path = join(TMP, 'changelog/v1.0.0.md');
+    createFile(path, '# Changelog: v1.0.0\n\n## Added\n- First release');
+    expect(readFileSync(path, 'utf-8')).toContain('First release');
+  });
+
+  it('overwrites an existing file', () => {
+    const path = join(TMP, 'test.md');
+    createFile(path, 'first content');
+    createFile(path, 'second content');
+    expect(readFileSync(path, 'utf-8')).toBe('second content');
+  });
+
+  it('creates missing parent directories', () => {
+    const path = join(TMP, 'a/b/c/file.md');
+    createFile(path, 'content');
+    expect(existsSync(path)).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test -- tests/core/writer.test.ts
+```
+
+Expected: FAIL — `Cannot find module '../../src/core/writer.js'`
+
+- [ ] **Step 3: Create src/core/writer.ts**
+
+```typescript
+// src/core/writer.ts
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+
+export function appendSection(filePath: string, heading: string, content: string): void {
+  ensureDir(filePath);
+  const section = `\n## ${heading}\n\n${content}\n`;
+  if (existsSync(filePath)) {
+    const existing = readFileSync(filePath, 'utf-8');
+    writeFileSync(filePath, existing + section, 'utf-8');
+  } else {
+    writeFileSync(filePath, section.trimStart(), 'utf-8');
+  }
+}
+
+export function createFile(filePath: string, content: string): void {
+  ensureDir(filePath);
+  writeFileSync(filePath, content, 'utf-8');
+}
+
+function ensureDir(filePath: string): void {
+  const dir = dirname(filePath);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npm test -- tests/core/writer.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/writer.ts tests/core/writer.test.ts
+git commit -m "feat: add file writer utilities"
+```
+
+---
+
+## Task 7: Document Generator
+
+**Files:**
+- Create: `src/core/generator.ts`
+- Create: `tests/core/generator.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```typescript
+// tests/core/generator.test.ts
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { generateDocs, writeResults } from '../../src/core/generator.js';
+import type { AIProvider } from '../../src/ai/interface.js';
+import type { DiffResult } from '../../src/core/diff.js';
+
+const TMP = join(import.meta.dirname, '../../tmp-generator-test');
+
+beforeEach(() => mkdirSync(TMP, { recursive: true }));
+afterEach(() => rmSync(TMP, { recursive: true, force: true }));
+
+const mockAI: AIProvider = {
+  generate: vi.fn().mockResolvedValue('AI generated content for this section'),
+};
+
+const fakeDiff: DiffResult = {
+  raw: 'diff --git a/src/auth/login.ts b/src/auth/login.ts\n+new code',
+  prevTag: 'v1.0.0',
+  currentTag: 'v1.1.0',
+  changedFiles: ['src/auth/login.ts'],
+  fileGroups: {
+    frontend: [],
+    schema: [],
+    auth: ['src/auth/login.ts'],
+    infra: [],
+    other: [],
+  },
+};
+
+describe('generateDocs', () => {
+  it('calls AI for each target and returns results', async () => {
+    const results = await generateDocs(mockAI, fakeDiff, ['AGENTS.md', 'ARCHITECTURE.md']);
+    expect(results).toHaveLength(2);
+    expect(results[0].target).toBe('AGENTS.md');
+    expect(results[0].content).toBe('AI generated content for this section');
+    expect(mockAI.generate).toHaveBeenCalledTimes(2);
+  });
+
+  it('captures errors without throwing', async () => {
+    const failingAI: AIProvider = {
+      generate: vi.fn().mockRejectedValue(new Error('API rate limit')),
+    };
+    const results = await generateDocs(failingAI, fakeDiff, ['AGENTS.md']);
+    expect(results[0].error).toContain('API rate limit');
+    expect(results[0].content).toBe('');
+  });
+
+  it('runs targets concurrently', async () => {
+    const delays: number[] = [];
+    const timedAI: AIProvider = {
+      generate: vi.fn().mockImplementation(async () => {
+        delays.push(Date.now());
+        await new Promise(r => setTimeout(r, 50));
+        return 'content';
+      }),
+    };
+    const start = Date.now();
+    await generateDocs(timedAI, fakeDiff, ['AGENTS.md', 'ARCHITECTURE.md', 'DESIGN.md']);
+    const elapsed = Date.now() - start;
+    // Three 50ms tasks running concurrently should finish in ~50-100ms, not ~150ms
+    expect(elapsed).toBeLessThan(130);
+  });
+});
+
+describe('writeResults', () => {
+  it('writes AGENTS.md as appended section', async () => {
+    const results = await generateDocs(mockAI, fakeDiff, ['AGENTS.md']);
+    const written = writeResults(results, fakeDiff, TMP);
+    expect(written).toContain(`${TMP}/AGENTS.md`);
+    const content = readFileSync(`${TMP}/AGENTS.md`, 'utf-8');
+    expect(content).toContain('## Changes in v1.1.0');
+  });
+
+  it('creates changelog file at versioned path', async () => {
+    const results = await generateDocs(mockAI, fakeDiff, ['changelog']);
+    writeResults(results, fakeDiff, TMP);
+    expect(existsSync(`${TMP}/changelog/v1.1.0.md`)).toBe(true);
+  });
+
+  it('creates design-doc at versioned path', async () => {
+    const results = await generateDocs(mockAI, fakeDiff, ['design-doc']);
+    writeResults(results, fakeDiff, TMP);
+    expect(existsSync(`${TMP}/docs/design-docs/v1.1.0.md`)).toBe(true);
+  });
+
+  it('skips results with errors', async () => {
+    const failingAI: AIProvider = {
+      generate: vi.fn().mockRejectedValue(new Error('fail')),
+    };
+    const results = await generateDocs(failingAI, fakeDiff, ['AGENTS.md']);
+    const written = writeResults(results, fakeDiff, TMP);
+    expect(written).toHaveLength(0);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test -- tests/core/generator.test.ts
+```
+
+Expected: FAIL — `Cannot find module '../../src/core/generator.js'`
+
+- [ ] **Step 3: Create src/core/generator.ts**
+
+```typescript
+// src/core/generator.ts
+import type { AIProvider } from '../ai/interface.js';
+import type { DocTarget } from './relevance.js';
+import type { DiffResult } from './diff.js';
+import { appendSection, createFile } from './writer.js';
+
+type PromptFn = (diff: DiffResult) => string;
+
+const PROMPTS: Record<DocTarget, PromptFn> = {
+  'AGENTS.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for AGENTS.md.
+Describe what AI coding agents need to know: new modules, interfaces, APIs, navigation patterns, new conventions.
+Write in present tense. Be specific and actionable. 2-4 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'ARCHITECTURE.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for ARCHITECTURE.md.
+Focus on: new layers, modules, dependency changes, new abstractions, removed or restructured components.
+Write in present tense. 2-3 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'DESIGN.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for DESIGN.md.
+Focus on key design decisions, why certain approaches were chosen, trade-offs made.
+Write in present tense. 2-3 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'FRONTEND.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for FRONTEND.md.
+Focus on new components, UI patterns, styling changes, frontend architecture changes.
+Write in present tense. 2-3 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'SECURITY.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for SECURITY.md.
+Focus on auth changes, permission model updates, new security boundaries, data handling changes.
+Write in present tense. 2-3 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'RELIABILITY.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a section for RELIABILITY.md.
+Focus on error handling improvements, retry logic, circuit breakers, observability changes.
+Write in present tense. 2-3 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'QUALITY_SCORE.md': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, write a quality assessment section.
+Assess test coverage changes, code complexity, technical debt introduced or resolved.
+Write in present tense. 1-2 paragraphs max.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'changelog': (diff) =>
+    `Write a changelog entry in Markdown for changes from ${diff.prevTag} to ${diff.currentTag}.
+
+Format:
+# Changelog: ${diff.currentTag}
+
+## Added
+- ...
+
+## Changed
+- ...
+
+## Fixed
+- ...
+
+## Removed
+- ...
+
+Be specific and engineer-focused. Only include sections with actual content.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'design-doc': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Write a design document for changes from ${diff.prevTag} to ${diff.currentTag}.
+
+Format:
+# Design: ${diff.currentTag}
+
+## Summary
+[What changed and why]
+
+## Design Decisions
+[Key decisions with rationale]
+
+## Agent Legibility Notes
+[What an AI coding agent needs to know to work in the updated codebase]
+
+## Technical Debt
+[Any shortcuts taken, what should be cleaned up later — or "None identified"]
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'design-doc-index': (diff) =>
+    `Return only a single Markdown list item for a docs index. Format:
+- [${diff.currentTag}](${diff.currentTag}.md) — One-sentence summary of changes.
+
+Changed files: ${diff.changedFiles.slice(0, 20).join(', ')}
+
+Return only the list item, nothing else.`,
+
+  'tech-debt-tracker': (diff) =>
+    `You are a technical writer following Harness Engineering documentation style.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, identify technical debt.
+
+Write this section:
+## ${diff.currentTag}
+
+### New debt
+- [Shortcuts, hacks, or deferred work visible in the diff — or "None identified"]
+
+### Resolved debt
+- [Cleanup or refactoring that resolves known issues — or "None identified"]
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'db-schema': (diff) =>
+    `You are a technical writer.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, document database schema changes.
+Focus only on schema changes visible in the diff: new tables, columns, indexes, constraints.
+Format as Markdown with clear table descriptions.
+If no schema changes: write "No schema changes in this release."
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+
+  'product-specs-index': (diff) =>
+    `Return only a single Markdown list item for a product specs index, or an empty string if no clear new feature.
+Format (if applicable): - [Feature Name](feature-name.md) — One-sentence description.
+
+Changed files: ${diff.changedFiles.slice(0, 20).join(', ')}
+
+Return only the list item or empty string, nothing else.`,
+
+  'references': (diff) =>
+    `You are a technical writer.
+
+Based on the git diff between ${diff.prevTag} and ${diff.currentTag}, identify new external libraries introduced.
+For each new library write:
+
+# library-name
+
+One paragraph: what it does and how it is used in this codebase.
+
+If no new external libraries: return an empty string.
+
+Git diff:
+${diff.raw.slice(0, 8000)}`,
+};
+
+export interface GenerationResult {
+  target: DocTarget;
+  content: string;
+  error?: string;
+}
+
+export async function generateDocs(
+  ai: AIProvider,
+  diff: DiffResult,
+  targets: DocTarget[]
+): Promise<GenerationResult[]> {
+  return Promise.all(
+    targets.map(async (target): Promise<GenerationResult> => {
+      try {
+        const prompt = PROMPTS[target](diff);
+        const content = await ai.generate(prompt);
+        return { target, content };
+      } catch (err) {
+        return { target, content: '', error: String(err) };
+      }
+    })
+  );
+}
+
+export function writeResults(
+  results: GenerationResult[],
+  diff: DiffResult,
+  cwd: string
+): string[] {
+  const written: string[] = [];
+  for (const result of results) {
+    if (result.error || !result.content.trim()) continue;
+    const path = writeResult(result, diff, cwd);
+    if (path) written.push(path);
+  }
+  return written;
+}
+
+function writeResult(
+  result: GenerationResult,
+  diff: DiffResult,
+  cwd: string
+): string | null {
+  const tag = diff.currentTag;
+  const heading = `Changes in ${tag}`;
+
+  const appendTargets: DocTarget[] = [
+    'AGENTS.md', 'ARCHITECTURE.md', 'DESIGN.md', 'FRONTEND.md',
+    'SECURITY.md', 'RELIABILITY.md', 'QUALITY_SCORE.md',
+  ];
+
+  if ((appendTargets as string[]).includes(result.target)) {
+    const path = `${cwd}/${result.target}`;
+    appendSection(path, heading, result.content);
+    return path;
+  }
+
+  switch (result.target) {
+    case 'changelog': {
+      const path = `${cwd}/changelog/${tag}.md`;
+      createFile(path, result.content);
+      return path;
+    }
+    case 'design-doc': {
+      const path = `${cwd}/docs/design-docs/${tag}.md`;
+      createFile(path, result.content);
+      return path;
+    }
+    case 'design-doc-index': {
+      const path = `${cwd}/docs/design-docs/index.md`;
+      appendSection(path, heading, result.content);
+      return path;
+    }
+    case 'tech-debt-tracker': {
+      const path = `${cwd}/docs/exec-plans/tech-debt-tracker.md`;
+      appendSection(path, heading, result.content);
+      return path;
+    }
+    case 'db-schema': {
+      const path = `${cwd}/docs/generated/db-schema.md`;
+      appendSection(path, heading, result.content);
+      return path;
+    }
+    case 'product-specs-index': {
+      if (!result.content.trim()) return null;
+      const path = `${cwd}/docs/product-specs/index.md`;
+      appendSection(path, heading, result.content);
+      return path;
+    }
+    case 'references': {
+      if (!result.content.trim()) return null;
+      const libName = extractLibName(result.content);
+      if (!libName) return null;
+      const path = `${cwd}/docs/references/${libName}-llms.txt`;
+      createFile(path, result.content);
+      return path;
+    }
+    default:
+      return null;
+  }
+}
+
+function extractLibName(content: string): string | null {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].toLowerCase().replace(/[^a-z0-9-]/g, '-') : null;
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+```bash
+npm test -- tests/core/generator.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/core/generator.ts tests/core/generator.test.ts
+git commit -m "feat: add document generator with prompts and concurrent execution"
+```
+
+---
+
+## Task 8: Platform Provider Interface + GitHub
+
+**Files:**
+- Create: `src/providers/interface.ts`
+- Create: `src/providers/github.ts`
+- Create: `tests/providers/github.test.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```typescript
+// tests/providers/github.test.ts
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { GitHubProvider } from '../../src/providers/github.js';
+
+vi.mock('child_process', () => ({
+  execSync: vi.fn().mockReturnValue('git@github.com:myorg/myrepo.git\n'),
+}));
+
+const mockOctokit = {
+  pulls: {
+    list: vi.fn().mockResolvedValue({ data: [] }),
+    create: vi.fn().mockResolvedValue({
+      data: { html_url: 'https://github.com/myorg/myrepo/pull/42', number: 42 },
+    }),
+    update: vi.fn().mockResolvedValue({
+      data: { html_url: 'https://github.com/myorg/myrepo/pull/1' },
+    }),
+  },
+};
+
+vi.mock('@octokit/rest', () => ({
+  Octokit: vi.fn().mockImplementation(() => mockOctokit),
+}));
+
+describe('GitHubProvider', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('parses owner and repo from SSH remote URL', () => {
+    expect(() => new GitHubProvider('token')).not.toThrow();
+  });
+
+  it('creates a PR and returns its URL', async () => {
+    const provider = new GitHubProvider('token');
+    const url = await provider.createOrUpdatePR({
+      branch: 'harness-docs/v1.1.0',
+      title: 'docs: update for v1.1.0',
+      body: 'Auto-generated docs update',
+      baseBranch: 'main',
+    });
+    expect(url).toBe('https://github.com/myorg/myrepo/pull/42');
+    expect(mockOctokit.pulls.create).toHaveBeenCalledWith(
+      expect.objectContaining({
+        head: 'harness-docs/v1.1.0',
+        base: 'main',
+      })
+    );
+  });
+
+  it('updates existing PR if one already exists for the branch', async () => {
+    mockOctokit.pulls.list.mockResolvedValueOnce({
+      data: [{ number: 1, html_url: 'https://github.com/myorg/myrepo/pull/1' }],
+    });
+    const provider = new GitHubProvider('token');
+    const url = await provider.createOrUpdatePR({
+      branch: 'harness-docs/v1.1.0',
+      title: 'docs: update for v1.1.0',
+      body: 'Updated',
+      baseBranch: 'main',
+    });
+    expect(mockOctokit.pulls.update).toHaveBeenCalled();
+    expect(mockOctokit.pulls.create).not.toHaveBeenCalled();
+    expect(url).toBe('https://github.com/myorg/myrepo/pull/1');
+  });
+
+  it('throws on unrecognized remote URL', () => {
+    const { execSync } = vi.mocked(await import('child_process'));
+    execSync.mockReturnValueOnce('https://not-github.com/something\n');
+    expect(() => new GitHubProvider('token')).toThrow('Cannot parse GitHub remote URL');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+```bash
+npm test -- tests/providers/github.test.ts
+```
+
+Expected: FAIL — `Cannot find module '../../src/providers/github.js'`
+
+- [ ] **Step 3: Create src/providers/interface.ts**
+
+```typescript
+// src/providers/interface.ts
+export interface PlatformProvider {
+  createOrUpdatePR(opts: {
+    branch: string;
+    title: string;
+    body: string;
+    baseBranch: string;
+  }): Promise<string>; // returns PR/MR URL
+}
+```
+
+- [ ] **Step 4: Create src/providers/github.ts**
+
+Note: The branch is already pushed by `cli.ts` via `git push`. This provider only creates/updates the PR via the GitHub API — it does NOT manage git refs.
+
+```typescript
+// src/providers/github.ts
+import { Octokit } from '@octokit/rest';
+import { execSync } from 'child_process';
+import type { PlatformProvider } from './interface.js';
+
+export class GitHubProvider implements PlatformProvider {
+  private octokit: Octokit;
+  private owner: string;
+  private repo: string;
+
+  constructor(token: string) {
+    this.octokit = new Octokit({ auth: token });
+    const remoteUrl = execSync('git remote get-url origin').toString().trim();
+    const match = remoteUrl.match(/github\.com[/:](.+?)\/(.+?)(?:\.git)?$/);
+    if (!match) throw new Error(`Cannot parse GitHub remote URL: ${remoteUrl}`);
+    this.owner = match[1];
+    this.repo = match[2];
+  }
+
+  async createOrUpdatePR(opts: {
+    branch: string;
+    title: string;
+    body: string;
+    baseBranch: string;
+  }): Promise<string> {
+    // Check for an existing open PR for this branch
+    const { data: existingPRs } = await this.octokit.pulls.list({
+      owner: this.owner,
+      repo: this.repo,
+      head: `${this.owner}:${opts.branch}`,
+      state: 'open',
+    });
+
+    if (existingPRs.length > 0) {
+      const { data: pr } = await this.octokit.pulls.update({
+        owner: this.owner,
+        repo: this.repo,
+        pull_number: existingPRs[0].number,
+        title: opts.title,
+        body: opts.body,
+      });
+      return pr.html_url;
+    }
+
+    const { data: pr } = await this.octokit.pulls.create({
+      owner: this.owner,
+      repo: this.repo,
+      title: opts.title,
+      body: opts.body,
+      head: opts.branch,
+      base: opts.baseBranch,
+    });
+    return pr.html_url;
+  }
+}
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+```bash
+npm test -- tests/providers/github.test.ts
+```
+
+Expected: PASS
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add src/providers/interface.ts src/providers/github.ts tests/providers/github.test.ts
+git commit -m "feat: add platform provider interface and GitHub implementation"
+```
+
+---
+
+## Task 9: GitLab Stub
+
+**Files:**
+- Create: `src/providers/gitlab.ts`
+
+- [ ] **Step 1: Create src/providers/gitlab.ts**
+
+```typescript
+// src/providers/gitlab.ts
+import type { PlatformProvider } from './interface.js';
+
+export class GitLabProvider implements PlatformProvider {
+  async createOrUpdatePR(_opts: {
+    branch: string;
+    title: string;
+    body: string;
+    baseBranch: string;
+  }): Promise<string> {
+    throw new Error(
+      'GitLab provider is not yet implemented. ' +
+      'Contributions welcome: https://github.com/your-org/harness-engineering-auto-docs'
+    );
+  }
+}
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add src/providers/gitlab.ts
+git commit -m "feat: add GitLab provider stub"
+```
+
+---
+
+## Task 10: CLI Entry Point
+
+**Files:**
+- Create: `src/cli.ts`
+- Create: `tests/integration/generate.test.ts`
+
+- [ ] **Step 1: Write the integration test**
+
+```typescript
+// tests/integration/generate.test.ts
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdirSync, rmSync, existsSync } from 'fs';
+import { join } from 'path';
+import { generateDocs, writeResults } from '../../src/core/generator.js';
+import { selectTargets } from '../../src/core/relevance.js';
+import { parseChangedFiles, groupFiles } from '../../src/core/diff.js';
+import { readFileSync } from 'fs';
+import type { AIProvider } from '../../src/ai/interface.js';
+
+const TMP = join(import.meta.dirname, '../../tmp-integration-test');
+const FIXTURE = readFileSync(
+  join(import.meta.dirname, '../fixtures/diff-schema.txt'), 'utf-8'
+);
+
+beforeEach(() => mkdirSync(TMP, { recursive: true }));
+afterEach(() => rmSync(TMP, { recursive: true, force: true }));
+
+describe('full pipeline: diff → relevance → generate → write', () => {
+  it('generates and writes expected documents for schema diff', async () => {
+    const changedFiles = parseChangedFiles(FIXTURE);
+    const fileGroups = groupFiles(changedFiles);
+    const targets = selectTargets(fileGroups, changedFiles);
+
+    expect(targets).toContain('db-schema');
+    expect(targets).toContain('AGENTS.md');
+
+    const mockAI: AIProvider = {
+      generate: vi.fn().mockResolvedValue('Auto-generated documentation content'),
+    };
+
+    const diff = {
+      raw: FIXTURE,
+      prevTag: 'v1.0.0',
+      currentTag: 'v1.1.0',
+      changedFiles,
+      fileGroups,
+    };
+
+    const results = await generateDocs(mockAI, diff, targets);
+    const written = writeResults(results, diff, TMP);
+
+    expect(written.length).toBeGreaterThan(0);
+    expect(existsSync(`${TMP}/AGENTS.md`)).toBe(true);
+    expect(existsSync(`${TMP}/docs/generated/db-schema.md`)).toBe(true);
+    expect(existsSync(`${TMP}/changelog/v1.1.0.md`)).toBe(true);
+    expect(existsSync(`${TMP}/docs/design-docs/v1.1.0.md`)).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run integration test to verify it passes**
+
+```bash
+npm test -- tests/integration/generate.test.ts
+```
+
+Expected: PASS (this tests the core pipeline, mocking AI)
+
+- [ ] **Step 3: Create src/cli.ts**
+
+```typescript
+#!/usr/bin/env node
+// src/cli.ts
+import { execSync } from 'child_process';
+import { extractDiff } from './core/diff.js';
+import { selectTargets } from './core/relevance.js';
+import { generateDocs, writeResults } from './core/generator.js';
+import { GitHubProvider } from './providers/github.js';
+import { GitLabProvider } from './providers/gitlab.js';
+import { AnthropicProvider } from './ai/anthropic.js';
+import { OpenAIProvider } from './ai/openai.js';
+import type { AIProvider } from './ai/interface.js';
+import type { PlatformProvider } from './providers/interface.js';
+
+function requireEnv(name: string): string {
+  const value = process.env[name];
+  if (!value) {
+    console.error(`Error: ${name} environment variable is required`);
+    process.exit(1);
+  }
+  return value;
+}
+
+function detectPlatform(): PlatformProvider {
+  if (process.env.GITHUB_ACTIONS) {
+    return new GitHubProvider(requireEnv('GITHUB_TOKEN'));
+  }
+  if (process.env.GITLAB_CI) {
+    return new GitLabProvider();
+  }
+  // Default to GitHub for local runs
+  const token = process.env.GITHUB_TOKEN;
+  if (!token) {
+    console.error('Error: GITHUB_TOKEN is required (or run in GITHUB_ACTIONS / GITLAB_CI)');
+    process.exit(1);
+  }
+  return new GitHubProvider(token);
+}
+
+function selectAI(model: string, apiKey: string): AIProvider {
+  if (model.startsWith('claude-')) return new AnthropicProvider(apiKey, model);
+  if (model.startsWith('gpt-')) return new OpenAIProvider(apiKey, model);
+  console.error(`Error: Unknown model "${model}". Use a claude-* or gpt-* model.`);
+  process.exit(1);
+}
+
+function getDefaultBranch(): string {
+  try {
+    return execSync('git symbolic-ref refs/remotes/origin/HEAD --short')
+      .toString().trim().replace('origin/', '');
+  } catch {
+    return 'main';
+  }
+}
+
+async function main() {
+  const model = requireEnv('AI_MODEL');
+  const apiKey = requireEnv('AI_API_KEY');
+
+  const diff = extractDiff();
+
+  if (!diff.raw.trim()) {
+    console.log('No diff between tags. Nothing to document.');
+    process.exit(0);
+  }
+
+  console.log(`Generating docs: ${diff.prevTag} → ${diff.currentTag}`);
+
+  const ai = selectAI(model, apiKey);
+  const targets = selectTargets(diff.fileGroups, diff.changedFiles);
+  console.log(`Updating ${targets.length} documents: ${targets.join(', ')}`);
+
+  const results = await generateDocs(ai, diff, targets);
+
+  const failures = results.filter(r => r.error);
+  if (failures.length > 0) {
+    console.warn(`\nWarning: ${failures.length} document(s) failed:`);
+    failures.forEach(f => console.warn(`  - ${f.target}: ${f.error}`));
+  }
+
+  const cwd = process.cwd();
+  const writtenFiles = writeResults(results.filter(r => !r.error), diff, cwd);
+  console.log(`\nWrote ${writtenFiles.length} files.`);
+
+  if (writtenFiles.length === 0) {
+    console.log('No files written. Skipping PR creation.');
+    process.exit(0);
+  }
+
+  // Git: create branch, commit, push
+  const branch = `harness-docs/${diff.currentTag}`;
+  const baseBranch = getDefaultBranch();
+
+  execSync(`git checkout -b ${branch}`);
+  execSync(`git add ${writtenFiles.map(f => `"${f}"`).join(' ')}`);
+  execSync(
+    `git commit -m "docs: Harness Engineering docs update for ${diff.currentTag}"`,
+    { env: { ...process.env, GIT_AUTHOR_NAME: 'harness-engineering-auto-docs', GIT_AUTHOR_EMAIL: 'bot@harness-engineering-auto-docs' } }
+  );
+  execSync(`git push -u origin ${branch}`);
+
+  // Create PR
+  const platform = detectPlatform();
+  const prUrl = await platform.createOrUpdatePR({
+    branch,
+    title: `docs: Harness Engineering docs for ${diff.currentTag}`,
+    body: [
+      `Auto-generated by [harness-engineering-auto-docs](https://github.com/your-org/harness-engineering-auto-docs).`,
+      ``,
+      `Updates documentation based on changes from **${diff.prevTag}** to **${diff.currentTag}**.`,
+      ``,
+      `**Updated files:**`,
+      writtenFiles.map(f => `- \`${f.replace(cwd + '/', '')}\``).join('\n'),
+    ].join('\n'),
+    baseBranch,
+  });
+
+  console.log(`\nPR created: ${prUrl}`);
+}
+
+main().catch(err => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});
+```
+
+- [ ] **Step 4: Run all tests**
+
+```bash
+npm test
+```
+
+Expected: All tests PASS
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/cli.ts tests/integration/generate.test.ts
+git commit -m "feat: add CLI entry point"
+```
+
+---
+
+## Task 11: Example Workflow + Build
+
+**Files:**
+- Create: `examples/github-workflow.yml`
+- Modify: `README.md`
+
+- [ ] **Step 1: Create examples/github-workflow.yml**
+
+```yaml
+# examples/github-workflow.yml
+# Copy this file to .github/workflows/harness-docs.yml in your target project.
+
+name: Harness Engineering Docs
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  update-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Required: fetch all tags for diff
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Generate and PR Harness Engineering docs
+        run: npx harness-engineering-auto-docs@latest
+        env:
+          AI_MODEL: claude-sonnet-4-6          # or gpt-4o
+          AI_API_KEY: ${{ secrets.AI_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+- [ ] **Step 2: Write README.md**
+
+```markdown
+# harness-engineering-auto-docs
+
+Auto-generate [Harness Engineering](https://openai.com/research/harness-engineering) style documentation when your project creates a git tag. Opens a PR with updated docs.
+
+## Usage
+
+Add `.github/workflows/harness-docs.yml` to your project (see `examples/github-workflow.yml`), then set:
+
+- `AI_API_KEY` — your Anthropic or OpenAI API key (repository secret)
+- `AI_MODEL` — model name, e.g. `claude-sonnet-4-6` or `gpt-4o`
+- `GITHUB_TOKEN` — provided automatically by GitHub Actions
+
+When you push a tag (`git tag v1.2.0 && git push --tags`), a PR is automatically opened with updated documentation.
+
+## What gets updated
+
+| File | Always | Conditional |
+|------|--------|-------------|
+| `AGENTS.md` | ✓ | |
+| `ARCHITECTURE.md` | ✓ | |
+| `DESIGN.md` | ✓ | |
+| `QUALITY_SCORE.md` | ✓ | |
+| `changelog/vX.Y.Z.md` | ✓ | |
+| `docs/design-docs/vX.Y.Z.md` | ✓ | |
+| `docs/design-docs/index.md` | ✓ | |
+| `docs/exec-plans/tech-debt-tracker.md` | ✓ | |
+| `FRONTEND.md` | | frontend files changed |
+| `SECURITY.md` | | auth/security files changed |
+| `RELIABILITY.md` | | infra files changed |
+| `docs/generated/db-schema.md` | | SQL/schema files changed |
+| `docs/product-specs/index.md` | | new features detected |
+| `docs/references/` | | new dependencies added |
+
+## Local run
+
+```bash
+AI_MODEL=claude-sonnet-4-6 AI_API_KEY=sk-ant-... GITHUB_TOKEN=ghp_... npx harness-engineering-auto-docs
+```
+
+## Supported models
+
+- Claude: `claude-sonnet-4-6`, `claude-opus-4-6`, `claude-haiku-4-5-20251001`
+- OpenAI: `gpt-4o`, `gpt-4o-mini`, `o3`
+
+## Future
+
+- GitLab support (MR creation)
+```
+
+- [ ] **Step 3: Build the project**
+
+```bash
+npm run build
+```
+
+Expected: `dist/` directory created with `cli.js` and all compiled files, no TypeScript errors.
+
+- [ ] **Step 4: Verify CLI is executable**
+
+```bash
+node dist/cli.js 2>&1 | head -5
+```
+
+Expected: Output starts with `Error: AI_MODEL environment variable is required` — confirms the CLI loads correctly.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add examples/github-workflow.yml README.md dist/
+git commit -m "feat: add example workflow, README, and build output"
+```
+
+---
+
+## Task 12: Full Test Suite
+
+- [ ] **Step 1: Run complete test suite**
+
+```bash
+npm test
+```
+
+Expected: All tests PASS, zero failures.
+
+- [ ] **Step 2: Verify test count**
+
+```bash
+npm test -- --reporter=verbose 2>&1 | tail -20
+```
+
+Expected: At minimum 20 tests across all files, all green.
+
+- [ ] **Step 3: Final commit**
+
+```bash
+git add -A
+git status
+# Verify nothing unexpected is staged
+git commit -m "chore: final cleanup and verified test suite"
+```