designdoc

designdoc

Harness-engineered codebase documentation pipeline.

Walks any repo bottom-up and emits a validated docs/design/ tree: per-class docs, package rollups, mermaid diagrams (syntax + semantics validated), a system-design rollup, a tech-debt ledger, and a YAML file of unresolved human-in-the-loop disputes.

Install

As a CLI

Install the designdoc command into a uv-managed tool environment:

uv tool install git+https://github.com/SpillwaveSolutions/docgen
designdoc generate --repo /path/to/your/repo --budget 5.00

(Alternatively, pipx install git+https://github.com/SpillwaveSolutions/docgen if you prefer pipx. Once published to PyPI, pip install designdoc will also work.)

As a Claude Code plugin

claude plugin marketplace add SpillwaveSolutions/docgen
claude plugin install designdoc

Adds a /designdoc slash command (generate | resume | status | resolve).

From a clone (development)

git clone https://github.com/SpillwaveSolutions/docgen
cd docgen
uv sync
uv run designdoc generate --repo /path/to/your/repo --budget 5.00

Output lands in <repo>/docs/design/.

Status

v1 complete, v1.1 incremental-regeneration landed. All nine pipeline stages are implemented, tested, and measured end-to-end. See plans/2026_04_16_designdoc_gen_v1.md for the task plan.

Measured performance

Against the tests/fixtures/tiny_repo fixture (5 Python files, 3 classes, 1 dep) on claude-sonnet-4-6 via a Claude Max subscription:

Run	Wall clock	Cost (SDK-reported)	LLM invocations
Cold (first run, parallelism=3)	~16 min	~$3.98	58
Cold (parallelism=1 baseline)	~26 min	~$4.57	60
Warm (no source changes)	< 1 sec	$0.00	0

Two v1.1 optimizations combine here:

• Parallelism: config.parallelism (default 3) caps concurrent doer/checker invocations in Stages 2/3/4/6 via asyncio.Semaphore. Cold-run wall clock drops ~37% on tiny_repo; bigger repos with more files will see larger gains. Tune via --parallelism N or [pipeline].parallelism in .designdoc.toml.
• Incremental: the warm run skips every stage via content-hash comparison against prev_hashes / rollup_hashes in the pipeline state. Any single-file edit regenerates only that file's class doc + its package rollup + the system rollup — not the whole tree.

Run designdoc status to see which caches are primed. Reproduce with task test-e2e (requires claude CLI logged in and npx on PATH).

Design principles (Gen 3 harness engineering)

1. Control flow lives in Python, not prompts.
2. Checkers run in their own context window (no self-grading).
3. Scopes are small and bounded (file → class → package → system).
4. Failures are loud (schema-validated verdicts, HIL YAML on dispute).
5. Reliability over speed (max_attempts=3, bounded parallelism).
6. Mermaid is syntax + semantics validated before shipping.

See CLAUDE.md / AGENT.md for the full invariants.

Development

Prerequisites

• Python 3.12+ (dev machine runs 3.13)
• uv for env management
• Task for running commands
• @mermaid-js/mermaid-cli via npx (auto-fetched at Stage 5 preflight)
• claude CLI (Claude Code) logged in to a Pro/Max subscription — used by the e2e / dogfood runs. No ANTHROPIC_API_KEY required.

Commands

task install         # uv sync — install deps
task test            # unit + integration, no real API
task test-unit       # unit tests only
task test-e2e        # e2e tests (requires API key + mmdc)
task lint            # ruff check
task format          # ruff format
task ci              # exactly what CI runs — must be green before push
task dogfood         # real pipeline run against tests/fixtures/tiny_repo

Run a single test:

uv run pytest tests/unit/test_loop.py::test_ships_with_hil_after_3_fails -v

Test-and-commit discipline

Every change follows TWRC: write the test, write the code, run task ci, commit.

CI parity: task ci must run the exact same commands as .github/workflows/test.yml. If you change one, change the other in the same commit. Every commit is a green checkpoint.

Layout