# ad2v

> ad2v (Agentic Development to Visualization) compares a repository with its spec-driven development (SDD) specs and writes one SQLite file, `*.ad2v`, that describes both sides as a single graph and records how spec items and code pair up. Every node gets a status with reasons: specified, implemented, verified, drift, missing, orphan, stale, needs_review, not_evaluable. Readers: a zoomable 2.5D map (`ad2v view`), epoch diffs for pull requests (`ad2v diff --format md`), and a read-only MCP server (`ad2v mcp`) for Claude, ChatGPT, VS Code and other MCP hosts.

Install: `pip install ad2v` (Python ≥ 3.11; the wheel includes the viewer and the MCP App). License: Apache-2.0. Current version: 0.7.0.

Key facts for agents:
- Extraction is deterministic and makes no LLM calls; ad2v only reads files and never imports or runs repository code, tests or Terraform.
- Code extraction is Python today (FastAPI, Flask, Starlette); other languages show as `not_evaluable`. Specs: OpenAPI, Gherkin, Markdown (ad2v convention, spec-kit, Kiro, requirement tables, user stories, EARS in English or Spanish).
- The optional LLM layer (`ad2v llm`) is bring-your-own-model, budgeted, and informative only.
- The `.ad2v` file is plain SQLite with a published schema; `ad2v validate` checks it.

## Docs

- [Full documentation in one file](https://ad2v.dev/llms-full.txt): README, quickstart, MCP, infra, plug-ins, security, spec convention and the format spec
- [Getting started](https://ad2v.dev/docs/): install, first map, own project, CLI reference, troubleshooting
- [README](https://github.com/shanglai/ad2v/blob/main/README.md): overview, CLI, manifest (`ad2v.yaml`)
- [Quickstart](https://github.com/shanglai/ad2v/blob/main/docs/quickstart.md): every step, executed by the test suite
- [MCP setup](https://github.com/shanglai/ad2v/blob/main/docs/mcp.md): Claude Desktop, Claude Code, VS Code; tools and troubleshooting
- [Spec Markdown convention](https://github.com/shanglai/ad2v/blob/main/docs/spec/spec-markdown-convention.md): the spec formats ad2v reads
- [Infrastructure layer](https://github.com/shanglai/ad2v/blob/main/docs/infra.md): Terraform plans, env-var bridge, C4 view
- [Plug-ins](https://github.com/shanglai/ad2v/blob/main/docs/plugins.md): language extractors and framework packs (`ad2v.api` 1.0)

## Specification

- [Format spec v0.7](https://github.com/shanglai/ad2v/blob/main/docs/spec/ad2v-format-v0.7.md): normative; SQLite layout, statuses, epochs, layout, MCP, infra
- [SQLite DDL](https://github.com/shanglai/ad2v/blob/main/schema/ad2v-v0.7.sql)
- [IR JSON Schema](https://github.com/shanglai/ad2v/blob/main/schema/ir-v0.7.schema.json)
- [Architecture decision records](https://github.com/shanglai/ad2v/tree/main/docs/adr)

## Optional

- [Live demo](https://ad2v.dev/demo/): the viewer with an 8-epoch example, in the browser
- [Security model](https://github.com/shanglai/ad2v/blob/main/docs/security.md)
- [GitHub Action example](https://github.com/shanglai/ad2v/blob/main/examples/github-action/ad2v-diff.yml): post an ad2v diff on every pull request
- [PyPI package](https://pypi.org/project/ad2v/)
- [Source repository](https://github.com/shanglai/ad2v)