harness-auto-docs 0.1.0 → 0.2.2

package/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Run tests
+        run: pnpm test

package/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'pnpm'
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+
+      - name: Configure npm authentication
+        run: echo '//registry.npmjs.org/:_authToken=${NPM_TOKEN}' > .npmrc
+
+      - name: Publish to npm
+        run: pnpm publish --no-git-checks
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/AGENTS.md

@@ -5,7 +5,7 @@ Read this file first, then follow the pointers below for deeper context.
 
 ## What this project does
 
-`harness-engineering-auto-docs` is a TypeScript CLI that auto-generates Harness Engineering-style
+`harness-auto-docs` is a TypeScript CLI that auto-generates Harness Engineering-style
 documentation when a git tag is pushed. It diffs two adjacent tags, selects relevant
 doc targets, calls an LLM (Claude or GPT), writes Markdown files, and opens a GitHub PR.
 
@@ -40,6 +40,12 @@ doc targets, calls an LLM (Claude or GPT), writes Markdown files, and opens a Gi
 | `docs/product-specs/index.md` | Feature spec index |
 | `docs/references/` | Library-specific LLM reference files |
 
+## Keeping documentation in sync
+
+- **README.md must be updated on every project change.** Since agents can only see repo-local artifacts, stale README content is invisible and misleading. Any PR that changes functionality, API, or configuration must update the corresponding README section.
+- **Knowledge lives in `docs/` as the system of record.** `AGENTS.md` is the table of contents (~100 lines), not the encyclopedia. Deep context lives in structured `docs/` files.
+- **Doc-gardening is continuous.** A recurring process scans for stale or obsolete documentation that does not reflect real code and opens fix-up pull requests.
+
 ## Conventions
 
 - **Language / runtime**: TypeScript, ESM (`"type": "module"`), Node ≥18, built with `tsc`

package/ARCHITECTURE.md

@@ -1,11 +1,11 @@
 # ARCHITECTURE.md
 
-Top-level architecture of `harness-engineering-auto-docs`.
+Top-level architecture of `harness-auto-docs`.
 See `AGENTS.md` for navigation and `docs/design-docs/` for per-release decisions.
 
 ## Overview
 
-`harness-engineering-auto-docs` is a single-binary CLI (Node.js ESM) with no server or database.
+`harness-auto-docs` is a single-binary CLI (Node.js ESM) with no server or database.
 It is invoked once per git tag event, runs to completion, and exits.
 
 ```
@@ -48,7 +48,7 @@ cli.ts  (orchestration)
 ```
 git tag push
   → GitHub Actions triggers workflow
-  → npx harness-engineering-auto-docs
+  → npx harness-auto-docs
       → extractDiff()        reads git history, returns DiffResult
       → selectTargets()      classifies files, returns DocTarget[]
       → generateDocs()       calls AI provider in parallel, returns GenerationResult[]

package/README.md

@@ -1,4 +1,4 @@
-# harness-engineering-auto-docs
+# harness-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.
 
@@ -34,7 +34,7 @@ When you push a tag (`git tag v1.2.0 && git push --tags`), a PR is automatically
 ## Local run
 
 ```bash
-AI_MODEL=claude-sonnet-4-6 AI_API_KEY=sk-ant-... GITHUB_TOKEN=ghp_... npx harness-engineering-auto-docs
+AI_MODEL=claude-sonnet-4-6 AI_API_KEY=sk-ant-... GITHUB_TOKEN=ghp_... npx harness-auto-docs
 ```
 
 ## Supported models

package/dist/cli.js

@@ -79,14 +79,14 @@ async function main() {
     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 commit -m "docs: Harness Engineering docs update for ${diff.currentTag}"`, { env: { ...process.env, GIT_AUTHOR_NAME: 'harness-auto-docs', GIT_AUTHOR_EMAIL: 'bot@harness-auto-docs' } });
     execSync(`git push -u origin ${branch}`);
     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).`,
+            `Auto-generated by [harness-auto-docs](https://github.com/chooin/harness-auto-docs).`,
             ``,
             `Updates documentation based on changes from **${diff.prevTag}** to **${diff.currentTag}**.`,
             ``,

package/dist/providers/gitlab.js

@@ -1,6 +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');
+            'Contributions welcome: https://github.com/chooin/harness-auto-docs');
     }
 }

package/docs/DESIGN.md

@@ -1,6 +1,6 @@
 # DESIGN.md
 
-Design philosophy and key decisions for `harness-engineering-auto-docs`.
+Design philosophy and key decisions for `harness-auto-docs`.
 See `docs/design-docs/` for per-release design documents.
 
 ## Core philosophy
@@ -12,7 +12,7 @@ keeping repository knowledge current. Based on lessons from the Harness Engineer
 > "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
+`harness-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

package/docs/QUALITY_SCORE.md

@@ -1,7 +1,7 @@
 # QUALITY_SCORE.md
 
 Quality grades for each domain and architectural layer.
-Updated on each release by `harness-engineering-auto-docs` itself.
+Updated on each release by `harness-auto-docs` itself.
 
 ## Grading legend
 

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

@@ -1,6 +1,6 @@
 # Core Beliefs
 
-Agent-first operating principles for `harness-engineering-auto-docs`.
+Agent-first operating principles for `harness-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)
@@ -40,7 +40,7 @@ The knowledge store is organized so each layer reveals more detail than the last
 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
+**Implication**: `harness-auto-docs` is a mechanical enforcement tool — it runs automatically
 on every tag, not on request.
 
 ## 6. Continuous small increments beat periodic big fixes

package/docs/design-docs/index.md

@@ -1,6 +1,6 @@
 # Design Docs Index
 
-Catalogued design documents for `harness-engineering-auto-docs`.
+Catalogued design documents for `harness-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
@@ -8,7 +8,7 @@ that underpin every design decision in this project.
 
 ## Releases
 
-<!-- harness-engineering-auto-docs appends entries here on each release -->
+<!-- harness-auto-docs appends entries here on each release -->
 
 _No releases yet. The first tagged release will appear here._
 

package/docs/exec-plans/tech-debt-tracker.md

@@ -1,6 +1,6 @@
 # Tech Debt Tracker
 
-Tracks known technical debt in `harness-engineering-auto-docs`.
+Tracks known technical debt in `harness-auto-docs`.
 Updated automatically on each release. See `docs/QUALITY_SCORE.md` for graded gap tracking.
 
 ---
@@ -23,4 +23,4 @@ _None yet — first baseline._
 
 ---
 
-<!-- harness-engineering-auto-docs appends sections here on each release -->
+<!-- harness-auto-docs appends sections here on each release -->

package/docs/product-specs/index.md

@@ -1,9 +1,9 @@
 # Product Specs Index
 
-Feature specifications for `harness-engineering-auto-docs`.
+Feature specifications for `harness-auto-docs`.
 Each entry links to a spec document for a significant feature addition.
 
-<!-- harness-engineering-auto-docs appends entries here when new features are detected in a release -->
+<!-- harness-auto-docs appends entries here when new features are detected in a release -->
 
 ## Shipped features
 
@@ -13,7 +13,7 @@ Each entry links to a spec document for a significant feature addition.
 selects relevant documentation targets, calls an LLM to generate content, writes Markdown files,
 and opens a GitHub PR with the updates.
 
-**Trigger**: `git tag v*` → GitHub Actions workflow → `npx harness-engineering-auto-docs`
+**Trigger**: `git tag v*` → GitHub Actions workflow → `npx harness-auto-docs`
 
 **Inputs**: `AI_MODEL`, `AI_API_KEY`, `GITHUB_TOKEN` (environment variables)
 

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

@@ -1,8 +1,8 @@
-# Harness Engineering Auto Docs Implementation Plan
+# Harness 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.
+**Goal:** Build and publish an npm CLI package (`harness-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.
 
@@ -13,7 +13,7 @@
 ## File Structure
 
 ```
-harness-engineering-auto-docs/
+harness-auto-docs/
 ├── package.json
 ├── tsconfig.json
 ├── vitest.config.ts
@@ -63,12 +63,12 @@ harness-engineering-auto-docs/
 
 ```json
 {
-  "name": "harness-engineering-auto-docs",
+  "name": "harness-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"
+    "harness-auto-docs": "./dist/cli.js"
   },
   "scripts": {
     "build": "tsc",
@@ -1487,7 +1487,7 @@ export class GitLabProvider implements PlatformProvider {
   }): Promise<string> {
     throw new Error(
       'GitLab provider is not yet implemented. ' +
-      'Contributions welcome: https://github.com/your-org/harness-engineering-auto-docs'
+      'Contributions welcome: https://github.com/chooin/harness-auto-docs'
     );
   }
 }
@@ -1669,7 +1669,7 @@ async function main() {
   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' } }
+    { env: { ...process.env, GIT_AUTHOR_NAME: 'harness-auto-docs', GIT_AUTHOR_EMAIL: 'bot@harness-auto-docs' } }
   );
   execSync(`git push -u origin ${branch}`);
 
@@ -1679,7 +1679,7 @@ async function main() {
     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).`,
+      `Auto-generated by [harness-auto-docs](https://github.com/chooin/harness-auto-docs).`,
       ``,
       `Updates documentation based on changes from **${diff.prevTag}** to **${diff.currentTag}**.`,
       ``,
@@ -1751,7 +1751,7 @@ jobs:
           node-version: '20'
 
       - name: Generate and PR Harness Engineering docs
-        run: npx harness-engineering-auto-docs@latest
+        run: npx harness-auto-docs@latest
         env:
           AI_MODEL: claude-sonnet-4-6          # or gpt-4o
           AI_API_KEY: ${{ secrets.AI_API_KEY }}
@@ -1761,7 +1761,7 @@ jobs:
 - [ ] **Step 2: Write README.md**
 
 ```markdown
-# harness-engineering-auto-docs
+# harness-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.
 
@@ -1797,7 +1797,7 @@ When you push a tag (`git tag v1.2.0 && git push --tags`), a PR is automatically
 ## Local run
 
 ```bash
-AI_MODEL=claude-sonnet-4-6 AI_API_KEY=sk-ant-... GITHUB_TOKEN=ghp_... npx harness-engineering-auto-docs
+AI_MODEL=claude-sonnet-4-6 AI_API_KEY=sk-ant-... GITHUB_TOKEN=ghp_... npx harness-auto-docs
 ```
 
 ## Supported models

package/docs/superpowers/specs/{2026-04-03-harness-engineering-auto-docs-design.md → 2026-04-03-harness-auto-docs-design.md}

@@ -1,11 +1,11 @@
-# Harness Engineering Auto Docs — Design Spec
+# Harness Auto Docs — Design Spec
 
 **Date:** 2026-04-03
 **Status:** Approved
 
 ## Overview
 
-A CLI tool published as an npm package (`harness-engineering-auto-docs`) that automatically generates and updates Harness Engineering-style documentation when a GitHub/GitLab project creates a new tag. The tool runs via `npx harness-engineering-auto-docs` inside CI and opens a PR/MR with the updated docs.
+A CLI tool published as an npm package (`harness-auto-docs`) that automatically generates and updates Harness Engineering-style documentation when a GitHub/GitLab project creates a new tag. The tool runs via `npx harness-auto-docs` inside CI and opens a PR/MR with the updated docs.
 
 **Core constraint:** Context source is git diff only (prev_tag → current_tag). No full-repo reads.
 
@@ -148,7 +148,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0   # required: fetch all tags
-      - run: npx harness-engineering-auto-docs@latest
+      - run: npx harness-auto-docs@latest
         env:
           AI_MODEL: claude-sonnet-4-6
           AI_API_KEY: ${{ secrets.AI_API_KEY }}
@@ -158,7 +158,7 @@ jobs:
 **Locally:**
 
 ```bash
-AI_MODEL=claude-sonnet-4-6 AI_API_KEY=sk-... GITHUB_TOKEN=... npx harness-engineering-auto-docs
+AI_MODEL=claude-sonnet-4-6 AI_API_KEY=sk-... GITHUB_TOKEN=... npx harness-auto-docs
 ```
 
 ## Out of Scope

package/examples/github-workflow.yml

@@ -25,7 +25,7 @@ jobs:
           node-version: '20'
 
       - name: Generate and PR Harness Engineering docs
-        run: npx harness-engineering-auto-docs@latest
+        run: npx harness-auto-docs@latest
         env:
           AI_MODEL: claude-sonnet-4-6          # or gpt-4o
           AI_API_KEY: ${{ secrets.AI_API_KEY }}

package/package.json

@@ -1,16 +1,10 @@
 {
   "name": "harness-auto-docs",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "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"
+    "harness-auto-docs": "./dist/cli.js"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.39.0",
@@ -26,5 +20,13 @@
   "engines": {
     "node": ">=18"
   },
-  "packageManager": "10.33.0"
-}
+  "publishConfig": {
+    "git-checks": false
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/cli.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/cli.ts

@@ -94,7 +94,7 @@ async function main() {
   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' } }
+    { env: { ...process.env, GIT_AUTHOR_NAME: 'harness-auto-docs', GIT_AUTHOR_EMAIL: 'bot@harness-auto-docs' } }
   );
   execSync(`git push -u origin ${branch}`);
 
@@ -103,7 +103,7 @@ async function main() {
     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).`,
+      `Auto-generated by [harness-auto-docs](https://github.com/chooin/harness-auto-docs).`,
       ``,
       `Updates documentation based on changes from **${diff.prevTag}** to **${diff.currentTag}**.`,
       ``,

package/src/providers/gitlab.ts

@@ -10,7 +10,7 @@ export class GitLabProvider implements PlatformProvider {
   }): Promise<string> {
     throw new Error(
       'GitLab provider is not yet implemented. ' +
-      'Contributions welcome: https://github.com/your-org/harness-engineering-auto-docs'
+      'Contributions welcome: https://github.com/chooin/harness-auto-docs'
     );
   }
 }