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 git@github.com: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:

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:

Tech Stack

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