harness-auto-docs

Auto-generate Harness Engineering style documentation when your project creates a git tag. Routine doc updates commit directly; significant changes open a PR.

Usage

GitHub Actions

Add .github/workflows/harness-docs.yml to your project (see examples/github-workflow.yml), then set:

• GitHub repository setting — Settings → Actions → General → Workflow permissions: choose Read and write permissions if your org default is read-only, and enable Allow GitHub Actions to create and approve pull requests so the default GITHUB_TOKEN can open or update pull requests.
• ANTHROPIC_API_KEY / OPENAI_API_KEY / MINIMAX_API_KEY / … — API key for the chosen provider (see Supported models below)
• AI_MODEL — model name, e.g. claude-sonnet-4-6, gpt-4o, or MiniMax-M2.7
• GITHUB_TOKEN — provided automatically by GitHub Actions
• HARNESS_DOCS_BASE_BRANCH (recommended in Actions) — PR base branch, e.g. ${{ github.event.repository.default_branch }}. Avoids relying on origin/HEAD in shallow or tag-only checkouts.
• HARNESS_DOCS_STRATEGY (optional) — auto (default) commits routine per-tag output directly when only core targets run, and opens a PR when conditional targets fire; direct always commits to the base branch; pr always opens a PR.

Merge strategy: With auto, core targets are the files the tool always generates (docs/design-docs/vX.Y.Z.md, design-doc index, tech-debt tracker). Entry docs such as AGENTS.md / ARCHITECTURE.md are not auto-appended—keep them curated in-repo. Conditional targets (frontend, security, infra, schema, new features/deps) still widen the scope and trigger a PR in auto mode.

When PRs are used, re-running the workflow for the same tag updates the existing harness-docs/v* branch: the CLI fetches that branch and pushes with --force-with-lease so a new doc commit can replace a previous one without a non-fast-forward error.

GitLab CI/CD

Add the job from examples/gitlab-ci.yml to your .gitlab-ci.yml, then set these CI/CD Variables (Settings → CI/CD → Variables):

• GITLAB_TOKEN — a Project Access Token or Personal Access Token with api + write_repository scopes (CI_JOB_TOKEN is used as a fallback for same-project MRs)
• ANTHROPIC_API_KEY / OPENAI_API_KEY / … — API key for the chosen provider
• AI_MODEL — model name

When you push a tag (git tag v1.2.0 && git push --tags), a Merge Request is automatically opened with updated documentation.

What gets updated

| File | Always | Conditional | |------|--------|-------------| | docs/design-docs/vX.Y.Z.md | ✓ | | | docs/design-docs/index.md | ✓ | (list line after HTML marker) | | docs/exec-plans/tech-debt-tracker.md | ✓ | (## vX.Y.Z section per release) | | AGENTS.md, ARCHITECTURE.md, docs/DESIGN.md, docs/QUALITY_SCORE.md | | Not auto-written — maintain manually | | docs/FRONTEND.md | | frontend files changed | | docs/SECURITY.md | | auth/security files changed | | docs/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

AI_MODEL=claude-sonnet-4-6 ANTHROPIC_API_KEY=sk-ant-... GITHUB_TOKEN=ghp_... npx harness-auto-docs

Supported models

Model routing is determined by the prefix of AI_MODEL:

| Prefix | Provider | API key env var | Example models | |--------|----------|-----------------|----------------| | claude-* | Anthropic | ANTHROPIC_API_KEY | claude-sonnet-4-6, claude-opus-4-6 | | gpt-* | OpenAI | OPENAI_API_KEY | gpt-4o, gpt-4o-mini, o3 | | MiniMax-* | MiniMax | MINIMAX_API_KEY | MiniMax-M2.7 | | qwen-* | Qwen (阿里云) | QWEN_API_KEY | qwen-turbo, qwen-plus, qwen-max | | glm-* | 智谱 | ZHIPU_API_KEY | glm-4, glm-4-flash | | deepseek-* | DeepSeek | DEEPSEEK_API_KEY | deepseek-chat, deepseek-coder | | doubao-* | 豆包 (ByteDance) | DOUBAO_API_KEY | doubao-pro-4k | | moonshot-* | Kimi (Moonshot) | KIMI_API_KEY | moonshot-v1-8k, moonshot-v1-32k | | grok-* | Grok (xAI) | GROK_API_KEY | grok-2, grok-beta |

Future

• GitLab self-hosted instance support (custom CI_SERVER_HOST)