Generate technical documentation from your codebase

Autonomous technical-documentation generator. Scans a codebase, extracts symbols, structures a doc skeleton, drafts sections, verifies consistency, and publishes Markdown — offline by default, smarter with a BYO-LLM CLI.

Overview

This pack provides an operational autonomous agent for generating and maintaining the technical documentation of a software project.

It includes an OODA loop dedicated to the docgen domain, versioned prompts, configuration templates and a set of installation, test and execution scripts.

The pack is designed to be self-hosted (BYO-LLM): no API key is included, no third-party dependency (Python stdlib only). The LLM adapter automatically detects your own CLI (claude-code, kimi, codex; override via PACK_LLM) and calls it as a subprocess. Without an LLM, the agent runs in deterministic mode and produces a basic documentation structure.

Target audience

• Teams that want up-to-date technical documentation without manual effort.
• Solo developers who want a README/API doc generated on every commit.
• LLM operators who want an autonomous, auditable documentation pipeline.

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                    Source code / repo / files                        │
└──────────────────────────────────┬──────────────────────────────────┘
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│  IDLE → DISCOVER → EXTRACT → STRUCTURE → DRAFT → VERIFY → PUBLISH   │
│                        OODA State Machine                            │
└──────────────────────────────────┬──────────────────────────────────┘
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│  Named prompts → Deterministic handler →  BYO-LLM Adapter           │
│  scripts/test_prompt.py    scripts/run_agent.py                     │
└──────────────────────────────────┬──────────────────────────────────┘
                                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│  SQLite queue  →  templates/*.yaml  →  docs/output/*.md              │
└─────────────────────────────────────────────────────────────────────┘

Pack contents

Quick installation

cd /opt/agents/agent-docgen-v1
bash install.sh

The installer checks for Python 3.10+, creates a venv, installs the dependencies, detects a local LLM provider and configures a systemd unit.

Immediate test

# Test the main prompt
python3 scripts/test_prompt.py --prompt codebase_scanner --input templates/source_schema.yaml

# Run the agent in dry-run mode
python3 scripts/run_agent.py --config scripts/config.yaml --dry-run

# Offline test suite
bash smoke_test.sh

Customization

1. Copy scripts/config.yaml to config.local.yaml.
2. Adapt the templates in templates/.
3. Plug your own code sources into run_agent.py or via agent.py enqueue.

See CUSTOMIZE.md for details.

Costs and limits

This pack favors deterministic logic for critical decisions. The LLM is used for semantic extraction, drafting and verification. See OPERATING_COST_ESTIMATE.md for the operating cost estimate.

Use a local model (Ollama)

The optional LLM step can also run on your own machine through Ollama, so no text leaves your server. No account and no API key.

ollama pull <model>               # any chat model you like
export PACK_LLM=ollama            # prefer Ollama even if a coding-agent CLI is installed
export PACK_OLLAMA_MODEL=<model>  # optional: default is the first chat model the server lists
python3 -c "import llm_adapter; print(llm_adapter.detect())"   # prints: ollama

• PACK_OLLAMA_HOST points to another server (default http://127.0.0.1:11434); OLLAMA_HOST is also read when PACK_LLM=ollama.
• PACK_OLLAMA_NUM_CTX sets the context size if your reports or prompts are long.
• Without PACK_LLM, a local Ollama server is used only when no Claude Code, Kimi Code or Codex CLI is found.
• If the server is down or the model is missing, the pack keeps working in its deterministic mode.

Learning memory (local and private)

Every LLM call this pack makes is journaled in ./.pack_memory/ next to the code, so the pack can improve for you. Nothing is ever sent anywhere.

• What is kept: the task name, the masked input, the masked answer, status and latency. Keys, tokens, e-mails, phone numbers, IP addresses, card and IBAN numbers and personal paths are masked before writing; the system prompt is never stored.
• Teach it: python3 pack_memory.py feedback last ok confirms a result, python3 pack_memory.py feedback last bad --fix "the right answer" corrects it. Confirmed and corrected runs are reused as validated examples when a similar input comes in. Unrated runs are never injected into a prompt.
• Find similar cases: python3 pack_memory.py similar "some text" and python3 pack_memory.py clusters (groups of near-identical failures) work in plain Python, no model needed. Optional meaning-based matching uses an embedding model you already run locally: python3 pack_memory.py enable-semantic (Ollama on this machine only).
• Share, only if you want: python3 pack_memory.py export writes an anonymised summary (counts, statuses, size buckets, no text) for you to review.
• Control: PACK_MEMORY=0 turns it off, PACK_MEMORY_STORE_TEXT=0 keeps fingerprints only, python3 pack_memory.py purge --yes wipes it.

License

Personal use per purchase. Resale prohibited.