The Bet
Enterprise documentation is where good intentions go to die. Teams write specs in Confluence, then never update them. Six months later, the docs describe a system that no longer exists. Our hypothesis: AI agents can keep docs alive if you treat specs as code — version-controlled, PR-triggered, and living in the repo alongside the source.
Not a chatbot that answers questions about stale docs. A GitHub App that watches what your team ships and keeps the specs current automatically.
What We Built
A Python/FastAPI GitHub App that hooks into the PR lifecycle and maintains living documentation. The core architecture:
- SPECWRIGHT.yaml config file in each repo defining which specs exist and what they cover
- FastAPI + uvicorn handling GitHub webhook events (PR opened, merged, push, issues, comments)
- Claude API (Anthropic SDK) analyzing diffs against existing specs to detect drift, with all-markdown PR analysis using the full search index for context
- Ticket sync engine with a GitHub Issues adapter (Jira/Linear planned) — bidirectional status mapping between spec sections and project management tools
- Spec search with Vertex AI embedding-based semantic search and BM25 keyword search, backed by Neon PostgreSQL, with TTL caching and webhook-driven invalidation
- Web dashboard (Jinja2 + HTMX) for browsing repos, specs, non-spec docs (ADRs, READMEs, changelogs), and search results, with Auth0 OIDC authentication
- MCP server for coding agent integration — lets tools like Claude Code query specs directly
- Spec realization — Claude evaluates acceptance criteria against PR code changes, tracks whether specs are being implemented (PR #67)
- Stale spec detection — monitors doc freshness against code activity and auto-files GitHub issues for stale specs (PR #67)
- Helm chart for self-hosted Kubernetes deployment on DigitalOcean (DOKS) with nginx-ingress and LetsEncrypt TLS
The spec format was the key design decision. We landed on a structured markdown format with machine-readable sections (Purpose, Architecture, Interfaces, Constraints) that gives the AI enough structure to make targeted updates rather than rewriting entire documents.
What Happened
Active development. Key milestones:
- Spec format designed and validated — tested against 6 real-world specs from different domains. The structured format lets Claude make surgical updates instead of wholesale rewrites.