# SpecVerse: Intent Is All You Need

The documentation hub for SpecVerse. Philosophy, the verification loop, and the doc map.

## Contents

- [The Problem](#the-problem) — why vibe coding fails, why traditional specification failed
- [The Insight](#the-insight) — from non-deterministic generation to verifiable creation
- [The Philosophy](#the-philosophy) — structured intent as the single source of truth
- [The Four Pillars](#the-four-pillars) — Human-Writable / AI-Writable / AI-Describable / AI-Implementable
- [The Documentation Stack](#the-documentation-stack) — map of the canonical guides
- [The Ecosystem](#the-ecosystem) — active repositories
- [What Makes This Different](#what-makes-this-different) — positioning
- [The Numbers](#the-numbers)
- [Roadmap](#roadmap)

---

## The Problem

Software development is being transformed by AI. Developers describe what they want in natural language, and AI generates code. This is fast, flexible, and increasingly capable. It's also fundamentally unreliable.

### The Vibe Coding Trap

AI coding tools — Cursor, Copilot, Windsurf, Claude Code — generate code from loose prompts. The same prompt produces different results on different days. There's no schema validating the output against the intent. No way to verify the generated system matches what was asked for. No mechanism to replay a successful generation reliably.

The faster we generate code, the faster we accumulate **architectural drift** — the gap between what was intended and what was built. Every AI-generated function that's "close enough" compounds the problem. What starts as a productivity boost becomes a maintenance liability, because nobody can point to a single document and say "this is what the system is supposed to do."

This is vibe coding: it feels productive, but there's no structural guarantee that what's built matches what was wanted.

### The Limits of Traditional Specification

Previous attempts to solve this problem — UML, formal methods, Model-Driven Architecture — failed for the opposite reason. They were precise but impractical:

- **Too rigid**: specifications couldn't evolve at the pace of development
- **Too complex**: learning the specification language was harder than writing the code
- **Disconnected from implementation**: the spec and the code were separate artifacts, so one always drifted from the other
- **Write-once**: specs were created at the start and abandoned once coding began
- **Not designed for AI consumption**: traditional specifications were created for human readers alone. They can't be reliably parsed, generated, or reasoned about by AI agents — making them unusable in modern agentic workflows

The result: specifications became shelfware. Nobody maintained them because maintaining a spec *and* the code was double the work with no enforced connection between them.

### The Gap

What's missing is a format for describing software systems that is **precise enough for machines** but **natural enough for humans**, that can be **verified automatically**, and that stays **connected to implementation** because it *is* the implementation's source of truth.

SpecVerse is that format.

---

## The Insight

The core insight behind SpecVerse is that AI-generated software doesn't have to be non-deterministic. The problem isn't that AI generates code — it's that AI generates code **without a verifiable specification to check against**.

If there's a structured format that captures architectural intent — one that both humans and AI can read and write — then:

1. **AI generation becomes verifiable**: generate a spec, validate it against a schema. Pass or fail. No ambiguity.
2. **Proven solutions become replayable**: when an AI solves a problem well, capture the solution as a deterministic template. Replay it reliably forever — zero tokens, near-instant execution, identical output every time.
3. **Architecture becomes auditable**: the spec is the source of truth. Compare the running system against the spec. If they match, the implementation is faithful. If they diverge, you can see exactly where.

This is the shift from **hallucinogenic generation to verifiable creation**: AI explores non-deterministically, humans verify, and proven solutions crystallise into deterministic, replayable artifacts.

```mermaid
flowchart LR
    subgraph "The Problem"
        VC["Vibe Coding
        Non-deterministic
        No verification
        Architectural drift"]
    end

    subgraph "The Bridge"
        SV["Structured Specification
        Schema-validated
        Human + AI readable
        Single source of truth"]
    end

    subgraph "The Outcome"
        VE["Verifiable Creation
        Verified output
        Replayable solutions
        Auditable architecture"]
    end

    VC -->|"SpecVerse"| SV --> VE

    style VC fill:#f5b7b1
    style SV fill:#e8daef,stroke:#7d3c98,stroke-width:2px
    style VE fill:#a8e6cf
```

SpecVerse implements this through a two-mode system:

**Generative mode** (the `ai template` command): an LLM generates a solution — a specification, a code template, a deployment configuration. The output is validated against the SpecVerse schema. Errors are automatically fixed through a validate-fix loop until the spec passes 100%. This costs tokens and takes seconds, but produces verified output.

**Deterministic mode** (the `realize` command): a proven solution is captured as an **instance factory** — a deterministic template generator stored in version control. Execution is deterministic, near-instant, costs nothing, and produces identical output every time.

Solutions graduate from generative to deterministic as they mature. When requirements change, they return to generative mode, get re-verified, and are re-captured.

The instance factory templates in SpecVerse — ORM schema generators, API route generators, UI component generators — are themselves **distilled LLM knowledge**: the best solution an AI produced, verified by a human, crystallised for reliable reuse.

---

## The Philosophy

> **Structured intent as the single source of truth.**

Software architecture should be expressed in a single, structured format that serves as the source of truth for both humans and machines. Previous approaches — UML, formal methods, Model-Driven Architecture — provided structure but failed in practice: they were too rigid to evolve, too complex to maintain, and too disconnected from implementation to stay current. Critically, they were never designed for a world where AI agents need to read, write, and reason about specifications alongside humans.

SpecVerse is built for that world. A SpecVerse specification is:

- **Readable** by any developer who can read YAML
- **Writable** by humans and AI systems alike
- **Verifiable** against a formal schema — pass or fail, no ambiguity
- **Precise enough** to generate implementations from, or to execute directly at runtime
- **Extractable** from existing codebases, creating a zero-risk adoption path

It captures the *what* and *why* of a system without dictating the *how*. The same specification can target different ORMs, web frameworks, or UI libraries — technology choices are made in the manifest, not the spec.

---

## The Four Pillars

The philosophy manifests through four structural capabilities — four directions that specifications can flow between humans and machines:

### Pillar 1: Human-Writable

Developers write specifications naturally using YAML with convention shortcuts:

```yaml
models:
  User:
    attributes:
      email: Email required unique verified
      name: String required
      role: String default=member values=[member, admin, moderator]
    lifecycles:
      account:
        flow: pending -> active -> suspended -> deleted
```

No special tools required. Any developer who can read YAML can read and modify a SpecVerse specification. Conventions like `Email required unique verified` expand into structured schema definitions automatically.

See [SPECVERSE-SPECIFYING.md](SPECVERSE-SPECIFYING.md) for the full language reference.

### Pillar 2: AI-Writable

An AI system receives a natural-language request — "build me a property management system with bookings, guest profiles, and multi-property support" — and generates a complete, valid specification. The specification is validated against the SpecVerse schema, and any errors are automatically fixed through the validate-fix loop until the spec passes 100%.

Measured performance: **4× expansion at personal scale** (40 lines of requirements → 200 lines of validated spec), **7.6× expansion at enterprise scale** (80 lines of requirements → 3,600 lines of spec with multi-tenancy / RBAC / compliance). See `specverse-demo-ai` for the evidence.

### Pillar 3: AI-Describable

An AI system examines an existing codebase — routes, database schemas, UI components — and extracts a specification describing what that system does. This creates an adoption path with zero risk: try SpecVerse on your existing code before committing to it.

### Pillar 4: AI-Implementable

A SpecVerse specification is precise and structured enough that an AI system can generate a working implementation from it — database schemas, API routes, service logic, UI components — targeting whatever technology stack is specified in the manifest.

### The Closed Loop: Verification Through Round-Trip

The four pillars aren't just independent capabilities — they form a **verification loop**:

```mermaid
flowchart LR
    A["Original Spec
    (intent)"] -->|"Pillar 4: Implement"| B["Running System
    (reality)"]
    B -->|"Pillar 3: Extract"| C["Extracted Spec
    (observed)"]
    C -->|"Compare"| D{"Match?"}
    D -->|"Yes"| E["Verified: Implementation
    is faithful"]
    D -->|"No"| F["Divergence detected"]
    F -->|"Fix spec or code"| A

    style A fill:#a8e6cf
    style B fill:#a8d8ea
    style C fill:#f9e2ae
    style E fill:#a8e6cf
    style F fill:#f5b7b1
```

After AI implements a system from a spec (Pillar 4), you can use Pillar 3 to extract a spec from the running implementation and compare it against the original. If they match, the implementation is faithful to intent. If they diverge, you can see exactly where and decide whether to fix the code or update the spec.

This closes the loop that traditional specification approaches left open. The spec doesn't drift from reality because you can always verify alignment — and the spec format is structured enough that comparison is meaningful, not just a text diff.

---

## The Documentation Stack

The canonical guides, each focused on a single concern:

| Guide | What it covers |
|---|---|
| **[SPECVERSE-SPECIFYING.md](SPECVERSE-SPECIFYING.md)** | Writing `.specly` files — models, controllers, services, events, views, deployments, extension entities, conventions, examples |
| **[SPECVERSE-TOOLING.md](SPECVERSE-TOOLING.md)** | The `spv` CLI — validate / infer / realize / init / gen / dev / cache / ai / session / smoke, manifests, publishing |
| **[SPECVERSE-API.md](SPECVERSE-API.md)** | Programmatic API — embed the engine (parse / infer / realize / generate) in your own tools, services, build steps, CI |
| **[SPECVERSE-APP-DEMO.md](SPECVERSE-APP-DEMO.md)** | The runtime interpreter — 9 tabs, hot reload, AI pane, 3D graph, server manager, deployment |
| **[SPECVERSE-REALIZING.md](SPECVERSE-REALIZING.md)** | Code generation deep dive — manifests, instance factories, capability resolution, L1/L2/L3 generation levels, the behavior walkthrough, the promotion lifecycle |
| **[SPECVERSE-EXTENDING.md](SPECVERSE-EXTENDING.md)** | Extending SpecVerse — add a new entity type, engine, instance factory, LLM provider; Quint formal verification; behavioural conventions |
| **[SPECVERSE-ARCHITECTURE.md](SPECVERSE-ARCHITECTURE.md)** | Internal system architecture — parse → infer → realize pipeline, entity modules, engine registry |

Plus focused deep-dives:

| Guide | What it covers |
|---|---|
| **[SPECVERSE-VIEW-RENDERING.md](SPECVERSE-VIEW-RENDERING.md)** | One pattern library, three consumers — the walker architecture shared across app-demo, ReactAppRuntime, ReactAppStarter |
| **[SPECVERSE-SELF-HOSTING.md](SPECVERSE-SELF-HOSTING.md)** | The bootstrap cycle — how specverse-self regenerates its own CLI (R30-R36) |
| **[GOLDEN-RULES.md](../GOLDEN-RULES.md)** | 44 permanent guiding principles across architecture / code generation / extension / quality / self-hosting / separation / bootstrap / documentation |

### Reading order

- **New user, first hour:** SPECVERSE-INTRO (this doc) → SPECVERSE-SPECIFYING quick-start → SPECVERSE-TOOLING install-and-smoke → try `spv init my-app` and poke around
- **Spec author:** SPECVERSE-SPECIFYING thoroughly → SPECVERSE-APP-DEMO for fast iteration
- **Developer generating code:** SPECVERSE-TOOLING → SPECVERSE-REALIZING → SPECVERSE-VIEW-RENDERING if customising frontends
- **Integrating the engine in code:** SPECVERSE-API → SPECVERSE-TOOLING (CLI equivalents) → SPECVERSE-REALIZING (manifests)
- **Contributor / extender:** SPECVERSE-EXTENDING → SPECVERSE-ARCHITECTURE → SPECVERSE-SELF-HOSTING → GOLDEN-RULES

---

## The Ecosystem

SpecVerse is a multi-repo ecosystem built around the `.specly` file as the central artifact. The production release is self-hosted: SpecVerse specified itself, generated its own CLI, and that generated CLI is the release.

### Core

| Repository | Role |
|---|---|
| [🔧 specverse-engines](https://github.com/SpecVerse/specverse-engines) | Engine source of truth — four npm packages (`@specverse/types`, `@specverse/entities`, `@specverse/engines`, `@specverse/runtime`) in a single workspace; `@specverse/assets` (prompts + examples + canonical content) ships from `specverse-self/assets` |
| [🚀 specverse-self](https://github.com/SpecVerse/specverse-self) | Production release — `@specverse/self` CLI, templates, examples, self-specification |
| [🎮 specverse-app-demo](https://github.com/SpecVerse/specverse-app-demo) | Dynamic runtime interpreter — executes specs at runtime, complement to static generation |
| [🧪 specverse-demo-self](https://github.com/SpecVerse/specverse-demo-self) | AI test laboratory — analyse / create / realize scoring against a versioned gold corpus |
| [📦 specverse-lang-registry](https://github.com/SpecVerse/specverse-lang-registry) | Community library platform — share/reuse `.specly` libraries via `@specverse/reg` CLI |
| [📚 specverse-lang-doc](https://github.com/SpecVerse/specverse-lang-doc) | Documentation site (Docusaurus) |

### Legacy

- **specverse-lang** — historical CLI orchestrator, superseded by specverse-self + the `@specverse/engines` subpath model. No new work lives there.
- **specverse-demo-ai** — earlier AI test laboratory (natural-language → `.specly` expansion metrics); archived, superseded by `specverse-demo-self`.
- **specverse-domain-company-model** / **specverse-domain-retail-commerce-model** — v3.1.0 example domain models; not tracking the current language.

### The Self-Hosting Proof

The strongest evidence that SpecVerse works is that it specified itself, generated itself, and the generated output is the production release.

```mermaid
flowchart LR
    subgraph "Phase 1: Create"
        REQ["Requirements
        (natural language)"] --> SPEC["921-line .specly
        (structured intent)"]
    end

    subgraph "Phase 2: Analyse"
        SPEC --> INF["Inference Engine
        expands to full architecture"]
    end

    subgraph "Phase 3: Realize"
        INF --> CODE["Generated Code
        465+ files
        backend + frontend + tools"]
    end

    subgraph "Phase 4: Materialise"
        CODE --> APP["Running Application
        Fastify + Prisma + SQLite
        + React + CLI"]
    end

    APP -->|"spec → code → running app"| PROOF["End-to-end: PROVEN"]

    style SPEC fill:#e8daef,stroke:#7d3c98,stroke-width:2px
    style PROOF fill:#a8e6cf,stroke:#2ecc71,stroke-width:3px
```

See [SPECVERSE-SELF-HOSTING.md](SPECVERSE-SELF-HOSTING.md) for the bootstrap cycle that enables this.

---

## What Makes This Different

There are many specification languages (OpenAPI, AsyncAPI, Terraform, Pulumi) and many AI coding tools (Cursor, Copilot, Windsurf). SpecVerse occupies a different space:

**It's not a code generator.** It's a format for expressing software architecture that happens to be implementable. The specification is the artifact, not the generated code. The self-hosting proof demonstrates this: a 921-line spec produces 465+ files of working code, but the spec is the source of truth — regenerate at any time and get identical output.

**It's not an API spec.** OpenAPI describes HTTP endpoints. SpecVerse describes entire systems — models, business logic, events, UI, deployment, and the relationships between them.

**It's not an IaC tool.** Terraform describes infrastructure. SpecVerse describes applications and maps them onto infrastructure through its deployment and manifest layers.

**It generates at three levels.** L1 (structural scaffolding), L2 (convention-based working code from 15 patterns), L3 (behavioural logic — including per-model constraint guards transpiled from declared `constraints:`, plus LLM-filled `steps:` bodies). Most generators stop at L1. (The spec itself is separately verified at validate time by transpiled Quint invariants — `spv validate --verify`.) See [SPECVERSE-REALIZING.md](SPECVERSE-REALIZING.md).

**It enforces business rules from the spec.** Models declare `constraints: [{on, requires}]` in natural-language sugar (`"Poll is open"`, `"User has not voted on Poll"`, `"Vote's choice is set"`). One spec line drives five enforcement surfaces in the realized application: FK dropdowns disable ineligible options, mutation buttons gate on parent state, a preflight `/validate` call fires before each request, server-side violations surface in a structured panel, and constraints needing server context show informationally in the form before submit. The author writes the rule once; the framework handles five UX outcomes. See the [Constraints](SPECVERSE-SPECIFYING.md#constraints) section.

**It's self-hosted.** SpecVerse is the only specification language that has specified itself, generated its own toolchain, and released the generated output as the production version. This isn't a theoretical capability — it's proven and shipping.

**It's a human-AI interface.** The specification format is designed so that humans can write it (Pillar 1), AI can generate it (Pillar 2), AI can extract it from existing systems (Pillar 3), and AI can implement from it (Pillar 4). No other tool is designed for all four.

The bet is that as AI becomes central to software development, the bottleneck shifts from "writing code" to "communicating intent precisely." SpecVerse is purpose-built for that world: one format, one source of truth, readable by humans, writable by machines, verifiable by both.

### Recently shipped capabilities (May 2026)

- **Phase 2 — Validate-Centric Constraints** (engines 6.66 → 6.75 across 15 slices, 2026-05-18/19). Models gain a `constraints: [{on, requires}]` block enforced across all CURVED operations in BOTH realized backends AND app-demo's dynamic interpreter. Nine sugar conventions desugar natural-language predicates (`"Poll is open"`, `"User has not voted on Poll"`, `"Vote's choice is set"`) into Quint guards that transpile to TypeScript. Five enforcement modes (α/γ/δ/ε/ζ) drive five UX surfaces in the realized React app from one spec rule. Actor wired through Fastify `request.user` into guards; throws are fail-OPEN (logged loudly, not blocking). Slice 15 adds: Create-time relation loading, async-ctx subquery execution (Vote.exists() actually runs), JIT interpreter evaluator, ID-based subquery comparison, and hard-fail parser (unresolvable constraints refuse to load instead of silently dropping). Lifecycle declarations auto-synthesize the corresponding attribute. 2919 tests; demo spec at `specverse-app-demo/examples/poll-vote-phase2.specly`.

### Recently shipped capabilities (April 2026)

- **Multi-component analyse** — extract a multi-component `.specly` spec from real codebases. Empirically validated against 8-component monorepo (idle-meta) producing 1351-line spec with 15 declarative `steps:` blocks; library references preserved end-to-end ("Sign tokens via jsonwebtoken library", "Compile and evaluate formula via expr-eval Parser library") through to AI-generated function bodies.
- **Structural prepass** — three pluggable backends (grep-only / CodeGraph / GitNexus) extract deterministic facts (entities, relationships, lifecycle states, method-level call graphs) from source code BEFORE the LLM sees it. Lifts analyse semantic accuracy from ~75% to ~100% on canonical cases. Per-framework adapter layer (TypeScript+Prisma, TypeScript+Decorators, multi-file Prisma) — ~10 frameworks cover ~90% of cases.
- **Four-mode AI provider system** — `claude-cli` (zero marginal cost on a Max subscription, ~98% token savings via session caching), `anthropic` (metered API), `openai-compatible` (DeepSeek/Groq/Together/Ollama/vLLM — 10-30× cheaper than Claude API), `stub` (no LLM, ambient runtime mode for MCP servers). Single env var switches between them.
- **`spv ai analyse` produces spec + manifest + deployments triple** — analyse extracts not just the spec but also the implementation manifest (what factories to use) and deployment topology in one pass.
- **`spv realize --estimate`** — cost/walltime projection before committing to a generation. Reports L1 (template) / L2 (convention) / L3 (AI) file counts with estimated cost on Max / Sonnet API / DeepSeek.
- **Multi-component realize fan-out** — when a spec has multiple components, all of them generate code, not just the first.

---

## The Numbers

| Metric | Value |
|--------|-------|
| npm packages | 5 (`@specverse/types` 5.4.2, `@specverse/entities` 5.7.2, `@specverse/engines` 6.97.12, `@specverse/runtime` 5.12.25, `@specverse/assets` 1.25.0) |
| Production CLI release | `@specverse/self` 5.21.6 |
| Pipeline-stage engines | 6 subpaths of `@specverse/engines` (parser, inference, realize, generators, ai, registry) + structural-prepass with 3 backends |
| Entity types | 11 (6 core + 5 extensions) |
| Facets per entity type | 9 (schema, conventions, inference, generators, behaviour, examples, tests, docs, behaviour grammars) |
| Inference rules | 21 deterministic |
| Convention patterns | 15 (L2 generation) |
| Quint verification | validate-time spec invariants (self-spec: 7/7 raw, 14/14 inferred) + runtime model-constraint guards |
| Instance factory categories | 13 |
| Composed examples | 54 |
| Self-spec | 921 lines, 5 components, 9 CLI commands |
| Tests (engines monorepo) | 1,588 (passing) |
| Golden Rules | 44 (R1–R36 + 8 sub-rules) |
| Prompt partials (DRY) | 10 shared partials across 6 active prompts |
| AI expansion ratio (measured) | 4× (personal) – 7.6× (enterprise) |

---

## Roadmap

The `.specly` format is designed to be extensible. These domains are planned additions — they require new entity modules, not architectural changes to the format itself:

| Specification Domain | Coverage | Priority |
|---------------------|----------|----------|
| Data Models & Relationships | Complete | — |
| Controllers / CURVED APIs | Complete | — |
| Business Services & Events | Complete | — |
| UI Views & Components | Complete | — |
| Lifecycle State Machines | Complete | — |
| Deployment Infrastructure | Complete | — |
| **Analytics & Reporting** | **Partial** (measures entity exists) | **High** |
| **External Integrations** | **Partial** (operation policies: retry, circuit breaker, rate limit) | **High** |
| **Data Pipelines** | **Planned** | **Medium** |
| **Workflow Orchestration** | **Planned** | **Medium** |
| Testing & Quality Contracts | Planned | Medium |
| Security Policies (ABAC) | Minimal | Medium |
| Internationalisation | Planned | Low |
| Multi-Tenancy (explicit) | Minimal | Low |
| Configuration Management | Minimal | Low |

The language is excellent for its core domain. The entity module system makes extension incremental: add a module with schema, conventions, inference rules, and generators, and the entire pipeline supports the new entity type without changing any engine code. See [SPECVERSE-EXTENDING.md](SPECVERSE-EXTENDING.md) for the step-by-step.

---

## Get Involved

- **Install and try:** `npm install -g @specverse/self` + `spv smoke` + `spv init my-app` (60-90 seconds)
- **Run a spec live:** clone `specverse-app-demo` and load `examples/blog.specly` for the fastest feedback loop
- **Read the 44 Golden Rules** at [GOLDEN-RULES.md](../GOLDEN-RULES.md)
- **Contribute:** see [specverse-self/CLAUDE.md](../../CLAUDE.md) for the development workflow