Changelog Doc Agent

AI-powered documentation automation agent. Generates user guides from Linear issues, compares docs against live product UI, creates changelogs from release cycles — all with human-in-the-loop approval.

Architecture

Two-layer design: n8n routes events, Python does the thinking.

Linear/GitHub webhook → n8n (filter + route) → Python FastAPI → Claude → MDX draft
                                                                           ↓
                                                              Streamlit Dashboard
                                                              (human review)
                                                                           ↓
                                                              Git PR → Mintlify docs

Pipelines

Pipeline	Trigger	Output
Doc Generation	Linear issue labeled doc-required	MDX user guide
Code Change Docs	GitHub PR merged	Updated API/feature docs
Changelog	Release cycle complete	User-facing changelog entry
Doc QA	Daily cron	Inconsistency report (docs vs live UI)
Structure Analysis	Weekly cron	Navigation and coverage recommendations

Key Features

• RAG-enhanced generation — ChromaDB stores existing docs + product copy, injected as context to prevent hallucination
• Hallucination guard — every fact claim cross-checked against Linear issue or code diff
• Prompt regression testing — golden input/output pairs, CI-enforced
• Dead letter queue — failed tasks captured with full traceback, retry/discard from dashboard
• Cost tracking — per-pipeline Claude API token usage and cost logged

Quick Start

cp .env.example .env        # Fill in API keys
pip install -r requirements.txt
playwright install chromium

make migrate                 # Run Alembic migrations
make seed                    # Load sample data

make dev                     # FastAPI on :8000
make dashboard               # Streamlit on :8501

# Or use Docker
make build && make up        # All services (API, worker, Redis, n8n, dashboard)

Commands

Command	Description
make dev	Start FastAPI dev server
make test	Run tests (66 tests, ~1s)
make test-prompts	Prompt regression tests (needs API key)
make lint	Ruff check + format
make typecheck	mypy type checking
make worker	Start Celery worker
make dashboard	Start Streamlit approval UI
make migrate	Apply DB migrations
make healthcheck	Check all system components
make cost-report	Claude API cost summary
make dlq-stats	Dead letter queue stats

Tech Stack

Component	Technology
LLM	Claude Sonnet 4.6 / Haiku 4.5
API	FastAPI + Celery + Redis
RAG	ChromaDB + sentence-transformers
UI QA	Playwright (headless Chromium)
Dashboard	Streamlit
Database	SQLite + Alembic (→ PostgreSQL)
Orchestration	n8n (5 workflow definitions)
Docs Platform	Mintlify (MDX)
Deploy	Docker Compose

Project Structure

├── src/
│   ├── pipelines/        # Doc generation, changelog, QA, structure analysis
│   ├── prompts/          # Version-controlled system prompts (v1.md per pipeline)
│   ├── agents/           # Claude agent base class
│   ├── integrations/     # Linear, GitHub, Mintlify API clients
│   ├── rag/              # ChromaDB embedding + retrieval
│   ├── validators/       # Hallucination guard
│   ├── approval/         # Git PR publisher
│   ├── webhooks/         # FastAPI webhook handlers + security
│   ├── dashboard/        # Streamlit approval UI
│   ├── schemas/          # Pydantic output models
│   └── db/               # SQLAlchemy models + Alembic migrations
├── n8n/                  # n8n workflow JSON exports
├── tests/
│   ├── unit/             # 40+ unit tests
│   ├── integration/      # Pipeline flow + webhook tests
│   └── prompts/          # Golden file regression tests
└── scripts/              # Operational utilities (backup, healthcheck, cost report)