gv-specwright 1.0.2

AI-native enterprise documentation platform

gv-exp-specwright

AI-native enterprise documentation platform. Living specs that generate tickets, AI agents that maintain docs, repo-native knowledge that replaces Confluence.

Status

Stage: Brief Started: 2026-02-06 Timebox: 4 weeks (2 concierge + 2 prototype) Budget: $500

Hypothesis

We believe that engineering orgs (50-500 devs) will replace Confluence with a repo-native documentation platform because AI agents can keep docs alive automatically, and structured specs that generate tickets and track implementation progress are more valuable than static wiki pages.

Links

• Experiment Brief
• Tracking Issue (see [EXPERIMENT] specwright)

Quick Start

# Clone
git clone [e-mail]:Gerner-Ventures/gv-exp-specwright.git
cd gv-exp-specwright

# Install all dependencies (backend + frontend)
make install

# Run tests
make test

# Run backend + frontend dev servers in parallel
make dev

Make Commands

Run make help for the full list. Highlights:

Command	Description
make install	Install backend + frontend dependencies
make dev	Run FastAPI dev server with Doppler secrets on :3000
make test	Run Python test suite
make lint	Lint backend (ruff) + frontend (eslint)
make format	Auto-fix and format Python code
make typecheck	Run mypy + vue-tsc type checks
make build	Build Vue SPA for production
make build-docker	Build production Docker image
make docker-dev	Run dev Docker image with source mounts
make helm-template	Render Helm chart locally
make clean-all	Remove all build artifacts + Docker images

Dev Environment (K8s)

Each developer gets an isolated environment on the shared DOKS cluster via DevSpace.

Prerequisites

• Docker (DevSpace builds images locally)
• DevSpace CLI (v6+)
• Doppler CLI — secrets management
• doctl — DigitalOcean CLI
• kubectl (installed via doctl)

One-time setup

doppler login
doctl auth init
doctl registry login                                      # DOCR auth
doctl kubernetes cluster kubeconfig save gv-shared        # kubeconfig

Daily workflow

export DEVSPACE_USERNAME=ng   # or set in .envrc

devspace dev                  # build, deploy, sync, port-forward
# → http://localhost:3000     (port-forwarded)
# → https://ng.specwright.gernerventures.com (ingress, after DNS setup)

devspace run logs             # tail pod logs
devspace run sync-secrets     # re-sync Doppler secrets
devspace run sync-trigger     # manually run reverse sync cron
devspace purge                # tear down dev environment

File changes in src/, templates/, and static/ sync into the pod and uvicorn auto-reloads.

See docs/self-hosting.md for production deployment and more details.

Architecture

Three-tier platform vision:

Tier	What	Status
Repo Agents	Per-repo spec parsing, PR analysis, doc maintenance, ticket sync	v0.1 target
Agent Mesh	Cross-repo impact analysis, conflict detection, dependency mapping	Future
Org Brain	Cross-repo search, ownership graph, decision index, onboarding gen	Future

Tech Stack

Component	Technology
Backend	Python 3.12+, FastAPI, uvicorn
Agent runtime	Anthropic Python SDK (Claude)
Spec parser	Custom markdown parser + python-frontmatter
Ticket sync	Jira REST API / Linear GraphQL API / GitHub Issues
Web UI	Vue 3, Vite, Tailwind CSS, Pinia
Hosting	Self-hosted K8s (DigitalOcean) via Helm chart
Secrets	Doppler
Dev tooling	DevSpace

Project Structure

src/specwright/
  main.py              # FastAPI app: webhook routes, health checks
  settings.py          # Pydantic Settings (env vars)
  github/              # GitHub App webhook handling
  agent/               # Claude agent runtime
  parser/              # Spec markdown parser + writer
  sync/                # Ticket sync engine + adapters
  config/              # SPECWRIGHT.yaml parser
  cron/                # Reverse sync cron job
  web/                 # Web routes (serves Vue SPA + Jinja2 fallback)
  cli.py               # CLI entrypoint
  mcp/                 # MCP server
frontend/              # Vue 3 SPA (Vite + Tailwind + Pinia)
tests/                 # pytest tests
templates/             # Jinja2 HTML templates (fallback)
static/                # CSS/JS/images + built SPA (static/app/)
chart/specwright/      # Helm chart for K8s deployment

Current Metrics

Metric	Target	Current
PM spec adoption	60%	-
Doc freshness	70%	-
Engineer engagement	40%	-
PM time saved	3 hrs/wk	-
Question answer quality	70%	-