Metadata-Version: 2.4
Name: gv-specwright
Version: 1.4.2
Summary: AI-native enterprise documentation platform
Project-URL: Homepage, https://specwright.gernerventures.com
Project-URL: Repository, https://github.com/Gerner-Ventures/gv-exp-specwright
Project-URL: Issues, https://github.com/Gerner-Ventures/gv-exp-specwright/issues
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: FastAPI
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: anthropic>=0.43
Requires-Dist: asyncpg>=0.30
Requires-Dist: authlib>=1.3
Requires-Dist: cryptography>=44.0
Requires-Dist: fastapi>=0.115
Requires-Dist: google-genai>=1.0
Requires-Dist: httpx>=0.28
Requires-Dist: itsdangerous>=2.1
Requires-Dist: jinja2>=3.1
Requires-Dist: mcp[cli]>=1.7
Requires-Dist: mistune>=3.1
Requires-Dist: opentelemetry-api>=1.20
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20
Requires-Dist: opentelemetry-sdk>=1.20
Requires-Dist: posthog>=3.7
Requires-Dist: pydantic-settings>=2.7
Requires-Dist: pydantic>=2.10
Requires-Dist: pyjwt[crypto]>=2.9
Requires-Dist: python-frontmatter>=1.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn[standard]>=0.34
Provides-Extra: dev
Requires-Dist: mypy>=1.14; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
Requires-Dist: pytest-cov>=6.0; extra == 'dev'
Requires-Dist: pytest-httpx>=0.35; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://github.com/Gerner-Ventures/gv-os/blob/main/docs/experiments/specwright.md)
- [Tracking Issue](https://github.com/Gerner-Ventures/gv-os/issues) (see [EXPERIMENT] specwright)

## Quick Start

```bash
# 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:

| 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](https://devspace.sh).

### Prerequisites

- [Docker](https://docs.docker.com/get-docker/) (DevSpace builds images locally)
- [DevSpace CLI](https://devspace.sh/docs/getting-started/installation) (v6+)
- [Doppler CLI](https://docs.doppler.com/docs/cli) — secrets management
- [doctl](https://docs.digitalocean.com/reference/doctl/) — DigitalOcean CLI
- kubectl (installed via `doctl`)

### One-time setup

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

### Daily workflow

```bash
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](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% | - |
