harness-auto-docs 0.1.0

package/dist/core/generator.js

@@ -0,0 +1,238 @@
+import { appendSection, createFile } from './writer.js';
+const PROMPTS = {
+    '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 docs/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 async function generateDocs(ai, diff, targets) {
+    return Promise.all(targets.map(async (target) => {
+        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, diff, cwd) {
+    const written = [];
+    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, diff, cwd) {
+    const tag = diff.currentTag;
+    const heading = `Changes in ${tag}`;
+    const appendTargets = [
+        'AGENTS.md', 'ARCHITECTURE.md', 'DESIGN.md', 'FRONTEND.md',
+        'SECURITY.md', 'RELIABILITY.md', 'QUALITY_SCORE.md',
+    ];
+    const rootTargets = ['AGENTS.md', 'ARCHITECTURE.md'];
+    if (appendTargets.includes(result.target)) {
+        const dir = rootTargets.includes(result.target) ? '' : 'docs/';
+        const path = `${cwd}/${dir}${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) {
+    const match = content.match(/^#\s+(.+)$/m);
+    return match ? match[1].toLowerCase().replace(/[^a-z0-9-]/g, '-') : null;
+}

package/dist/core/relevance.d.ts

@@ -0,0 +1,3 @@
+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';
+export declare function selectTargets(fileGroups: FileGroups, changedFiles: string[]): DocTarget[];

package/dist/core/relevance.js

@@ -0,0 +1,29 @@
+const CORE_TARGETS = [
+    'AGENTS.md',
+    'ARCHITECTURE.md',
+    'DESIGN.md',
+    'QUALITY_SCORE.md',
+    'changelog',
+    'design-doc',
+    'design-doc-index',
+    'tech-debt-tracker',
+];
+export function selectTargets(fileGroups, changedFiles) {
+    const targets = [...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)];
+}

package/dist/core/writer.d.ts

@@ -0,0 +1,2 @@
+export declare function appendSection(filePath: string, heading: string, content: string): void;
+export declare function createFile(filePath: string, content: string): void;

package/dist/core/writer.js

@@ -0,0 +1,23 @@
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from 'fs';
+import { dirname } from 'path';
+export function appendSection(filePath, heading, content) {
+    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, content) {
+    ensureDir(filePath);
+    writeFileSync(filePath, content, 'utf-8');
+}
+function ensureDir(filePath) {
+    const dir = dirname(filePath);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}

package/dist/providers/github.d.ts

@@ -0,0 +1,13 @@
+import type { PlatformProvider } from './interface.js';
+export declare class GitHubProvider implements PlatformProvider {
+    private octokit;
+    private owner;
+    private repo;
+    constructor(token: string);
+    createOrUpdatePR(opts: {
+        branch: string;
+        title: string;
+        body: string;
+        baseBranch: string;
+    }): Promise<string>;
+}

package/dist/providers/github.js

@@ -0,0 +1,43 @@
+import { Octokit } from '@octokit/rest';
+import { execSync } from 'child_process';
+export class GitHubProvider {
+    octokit;
+    owner;
+    repo;
+    constructor(token) {
+        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) {
+        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;
+    }
+}

package/dist/providers/gitlab.d.ts

@@ -0,0 +1,9 @@
+import type { PlatformProvider } from './interface.js';
+export declare class GitLabProvider implements PlatformProvider {
+    createOrUpdatePR(_opts: {
+        branch: string;
+        title: string;
+        body: string;
+        baseBranch: string;
+    }): Promise<string>;
+}

package/dist/providers/gitlab.js

@@ -0,0 +1,6 @@
+export class GitLabProvider {
+    async createOrUpdatePR(_opts) {
+        throw new Error('GitLab provider is not yet implemented. ' +
+            'Contributions welcome: https://github.com/your-org/harness-engineering-auto-docs');
+    }
+}

package/dist/providers/interface.d.ts

@@ -0,0 +1,8 @@
+export interface PlatformProvider {
+    createOrUpdatePR(opts: {
+        branch: string;
+        title: string;
+        body: string;
+        baseBranch: string;
+    }): Promise<string>;
+}

package/dist/providers/interface.js

@@ -0,0 +1 @@
+export {};

package/docs/DESIGN.md

@@ -0,0 +1,94 @@
+# DESIGN.md
+
+Design philosophy and key decisions for `harness-engineering-auto-docs`.
+See `docs/design-docs/` for per-release design documents.
+
+## Core philosophy
+
+This tool exists to automate the most expensive human bottleneck in agent-first development:
+keeping repository knowledge current. Based on lessons from the Harness Engineering experiment
+(OpenAI, Feb 2026), the single biggest drag on agent productivity is **stale or missing context**.
+
+> "From the agent's point of view, anything it can't access in-context while running effectively
+> doesn't exist." — Ryan Lopopolo, Harness Engineering
+
+`harness-engineering-auto-docs` makes repository knowledge self-maintaining: every git tag triggers a
+documentation pass, so the knowledge store reflects the codebase as it actually exists.
+
+## Key design decisions
+
+### 1. Tags as the documentation trigger (not commits)
+
+**Decision**: Generate docs on `git tag`, not on every commit or PR merge.
+
+**Rationale**: Tags represent meaningful semantic versions. Generating docs per-commit would
+flood the repository with micro-updates and overwhelm agents with noise. Tags mark intentional
+release points where a holistic documentation pass is appropriate.
+
+### 2. Diff-driven content (not full-file scans)
+
+**Decision**: Extract a `git diff` between adjacent tags and feed only that diff to the LLM.
+
+**Rationale**: Full-file analysis requires enormous context windows and is expensive. The diff
+is the minimal surface that conveys *what changed*. Prompts cap the diff at 8 000 characters
+to stay within reliable model context limits.
+
+**Trade-off**: Changes in very large diffs are truncated. Complex releases may miss some nuance.
+This is acceptable — the goal is progressive accumulation, not exhaustive single-pass coverage.
+
+### 3. Append-only for living documents, create-new for point-in-time docs
+
+**Decision**: `AGENTS.md`, `ARCHITECTURE.md`, `docs/DESIGN.md`, etc. are appended to with each
+release. `changelog/vX.Y.Z.md` and `docs/design-docs/vX.Y.Z.md` are created fresh.
+
+**Rationale**: Living documents accumulate knowledge over time. Per-release documents provide
+an immutable point-in-time record. This mirrors how architecture evolves alongside changelogs.
+
+### 4. File-group heuristics drive conditional doc targets
+
+**Decision**: Classify changed files into groups (`frontend`, `schema`, `auth`, `infra`) and
+only generate conditional docs when the relevant group is non-empty.
+
+**Rationale**: Generating `SECURITY.md` for a release that only touched CSS would produce
+meaningless filler. Conditional generation keeps each document signal-rich.
+
+**Trade-off**: Heuristics in `diff.ts:groupFiles` are regex-based and imprecise. False negatives
+are acceptable (some releases skip conditional docs they could have generated). False positives
+are more harmful — generating irrelevant content pollutes the knowledge store.
+
+### 5. Single AIProvider interface with prefix-based dispatch
+
+**Decision**: Model name prefix (`claude-*` / `gpt-*`) determines which provider is instantiated.
+
+**Rationale**: Users already know their model name. Adding a separate `AI_PROVIDER` env var
+would be redundant and error-prone. The prefix convention is unambiguous and self-documenting.
+
+### 6. No database, no server, no long-lived state
+
+**Decision**: The tool is a stateless CLI that runs to completion and exits.
+
+**Rationale**: Simplicity is a force multiplier for agents. A stateless tool is trivially
+reproducible, testable, and debuggable. All persistent state lives in the repository (git history,
+Markdown files). This is the Harness Engineering principle: repository-local, versioned artifacts
+are the system of record.
+
+### 7. AGENTS.md as table of contents, not encyclopedia
+
+**Decision**: This `AGENTS.md` is ~100 lines. It is a map with pointers, not a manual.
+
+**Rationale**: Directly from Harness Engineering lessons:
+- Large instruction files crowd out task context
+- "Too much guidance becomes non-guidance"
+- Monolithic files rot and become stale attractors
+
+The detailed knowledge lives in `ARCHITECTURE.md`, `docs/DESIGN.md`, `docs/design-docs/`, etc.,
+and agents navigate there via `AGENTS.md`.
+
+## What we intentionally did NOT do
+
+- **No semantic chunking or embeddings** — the tool targets small-to-medium diffs; retrieval
+  augmentation adds complexity without proportional benefit at this scale
+- **No multi-repo support** — each invocation operates on a single git repository
+- **No rollback mechanism** — doc updates are PR-based; rollback happens via normal git revert
+- **No GitLab MR** — stub exists in `src/providers/gitlab.ts` but is not implemented; see
+  `docs/exec-plans/tech-debt-tracker.md` for this as tracked debt

package/docs/QUALITY_SCORE.md

@@ -0,0 +1,74 @@
+# QUALITY_SCORE.md
+
+Quality grades for each domain and architectural layer.
+Updated on each release by `harness-engineering-auto-docs` itself.
+
+## Grading legend
+
+| Grade | Meaning |
+|-------|---------|
+| ✅ A | Solid — well-tested, clear interfaces, minimal debt |
+| 🟡 B | Adequate — works but has known gaps or rough edges |
+| 🟠 C | Needs attention — debt is accumulating or tests are sparse |
+| 🔴 D | Problematic — blocking issues or significant risk |
+
+---
+
+## v0.1.0 baseline (2026-04-03)
+
+### Core pipeline
+
+| Module | Grade | Notes |
+|--------|-------|-------|
+| `core/diff.ts` | ✅ A | Well-tested; `groupFiles` heuristics are simple and readable |
+| `core/relevance.ts` | ✅ A | Clean, pure function; full test coverage |
+| `core/generator.ts` | 🟡 B | Prompts are functional but not versioned; no prompt regression tests |
+| `core/writer.ts` | ✅ A | Minimal helpers; appendSection and createFile are straightforward |
+
+### AI layer
+
+| Module | Grade | Notes |
+|--------|-------|-------|
+| `ai/anthropic.ts` | ✅ A | Thin wrapper; tested with mocks |
+| `ai/openai.ts` | ✅ A | Thin wrapper; tested with mocks |
+| `ai/interface.ts` | ✅ A | Clean single-method interface |
+
+### Platform layer
+
+| Module | Grade | Notes |
+|--------|-------|-------|
+| `providers/github.ts` | 🟡 B | Creates/updates PRs correctly; `owner/repo` parsed from remote URL (fragile for non-standard remotes) |
+| `providers/gitlab.ts` | 🔴 D | **Not implemented** — throws on any call; this is tracked debt |
+
+### CLI orchestration
+
+| Module | Grade | Notes |
+|--------|-------|-------|
+| `cli.ts` | 🟡 B | Correct but dense; git operations are inline shell commands with no error recovery |
+
+### Test suite
+
+| Area | Grade | Notes |
+|------|-------|-------|
+| Unit coverage | 🟡 B | Core modules well covered; provider tests are mock-only |
+| Integration tests | 🟡 B | `tests/integration/generate.test.ts` covers happy path; no failure-path integration tests |
+| Fixtures | ✅ A | Diff fixtures in `tests/fixtures/` allow deterministic diff parsing tests |
+
+### Documentation
+
+| Area | Grade | Notes |
+|------|-------|-------|
+| README | ✅ A | Accurate and complete for users |
+| Knowledge store | 🟡 B | Baseline being established; will improve with each release |
+
+---
+
+## Gap tracking
+
+| Gap | Priority | Owner |
+|-----|----------|-------|
+| GitLab MR support | Medium | see `docs/exec-plans/tech-debt-tracker.md` |
+| Prompt regression tests | Low | no mechanism to detect prompt quality degradation |
+| `owner/repo` URL parsing robustness | Low | SSH remotes and non-GitHub hosts may fail |
+| Git operations error handling in `cli.ts` | Low | `execSync` throws on any git failure with no recovery |
+| Diff truncation strategy | Low | 8 000-char hard cut may slice mid-hunk |

package/docs/design-docs/core-beliefs.md

@@ -0,0 +1,71 @@
+# Core Beliefs
+
+Agent-first operating principles for `harness-engineering-auto-docs`.
+These beliefs inform every design decision and should be consulted when making trade-offs.
+
+Source: [Harness Engineering: Leveraging Codex in an Agent-First World](https://openai.com/index/harness-engineering/) (OpenAI, Feb 2026)
+
+---
+
+## 1. Humans steer. Agents execute.
+
+The human role is to define intent, set direction, and validate outcomes — not to write code
+line by line. This tool exists to reduce the human cost of keeping knowledge current so that
+agents can do more of the execution work.
+
+## 2. Repository knowledge is the system of record
+
+Anything not in the repository does not exist from the agent's perspective. Decisions made in
+chat threads, Slack, or people's heads are invisible to the system. All meaningful context must
+be committed as versioned, repository-local Markdown.
+
+**Implication for this tool**: Every documentation output is committed to the target repository.
+Nothing is written to an external system.
+
+## 3. AGENTS.md is a map, not a manual
+
+A short (`~100 lines`) `AGENTS.md` serves as an entry point with pointers to deeper documents.
+Long instruction files crowd out task context, rot quickly, and become non-guidance.
+
+**Implication**: This tool generates `AGENTS.md` by *appending* short sections — not by replacing
+or expanding it into an encyclopedia.
+
+## 4. Progressive disclosure over front-loading
+
+Agents start with a small, stable entry point (`AGENTS.md`) and navigate to specifics as needed.
+The knowledge store is organized so each layer reveals more detail than the last.
+
+## 5. Enforce invariants mechanically, not verbally
+
+Documentation alone cannot keep a codebase coherent. Rules that matter must be enforced via
+linters, type system constraints, or structural tests — not just written down and hoped about.
+
+**Implication**: `harness-engineering-auto-docs` is a mechanical enforcement tool — it runs automatically
+on every tag, not on request.
+
+## 6. Continuous small increments beat periodic big fixes
+
+Technical debt, like financial debt, compounds. The right strategy is continuous small paydowns
+(per-release doc updates, automated quality grading) rather than infrequent large efforts.
+
+## 7. Boring technology is better for agents
+
+Technologies with stable APIs, strong training data representation, and high composability are
+easier for agents to model correctly. Prefer well-established libraries over cutting-edge ones.
+Prefer reimplementing small subsets of functionality (with full test coverage and telemetry
+integration) over depending on opaque upstream behaviour.
+
+**Implication for this tool**: We use `@octokit/rest` (stable, well-documented) for GitHub and
+`@anthropic-ai/sdk` / `openai` (official SDKs with strong training data) for AI.
+
+## 8. Conditional generation over unconditional noise
+
+Generating a `SECURITY.md` section for a release that only touched CSS creates noise that
+degrades the signal-to-noise ratio of the knowledge store. Only generate documentation where
+there is real signal. Guard with file-group heuristics.
+
+## 9. Agent legibility is a first-class output
+
+Every feature should be evaluated not just for correctness but for whether it makes the
+codebase more legible to a future agent run. "Does this change make the repository easier
+for Codex to navigate and reason about?" is a valid and important design criterion.

package/docs/design-docs/index.md

@@ -0,0 +1,32 @@
+# Design Docs Index
+
+Catalogued design documents for `harness-engineering-auto-docs`.
+Each entry links to the per-release design document generated at tag time.
+
+See `docs/design-docs/core-beliefs.md` for the foundational agent-first operating principles
+that underpin every design decision in this project.
+
+## Releases
+
+<!-- harness-engineering-auto-docs appends entries here on each release -->
+
+_No releases yet. The first tagged release will appear here._
+
+---
+
+## Document structure
+
+Each design doc follows this template:
+
+```
+# Design: vX.Y.Z
+
+## Summary
+## Design Decisions
+## Agent Legibility Notes
+## Technical Debt
+```
+
+The **Agent Legibility Notes** section is specific to this project's Harness Engineering style:
+it explicitly calls out what an AI coding agent needs to understand to work correctly in the
+updated codebase after the release.