SpecVerse

Define Once, Implement Anywhere.

SpecVerse is a declarative specification language for defining business domains, models, and systems. Write a .specly specification, and the engine generates the complete application — backend, frontend, CLI, documentation, diagrams, and tools.

This repository is the self-specification — SpecVerse specifying and implementing itself. It's the production release.

How It Works

921-line self-spec  -->  [4 engine packages]  -->  465+ generated files
                                                    ├── Fastify REST API
                                                    ├── Prisma + SQLite
                                                    ├── React frontend (DevShell)
                                                    ├── 9-command CLI (commander)
                                                    ├── VSCode extension
                                                    ├── MCP server
                                                    └── 12+ Mermaid diagrams

Engine Packages

Published to npm under the @specverse scope. The toolchain uses subpath exports:

| Package | Version | Purpose | |---------|---------|---------| | @specverse/self | 5.17.20 | Production CLI + templates + self-specification | | @specverse/types | 5.2.0 | AST types, engine interfaces, shared spec-rules + step-matching types | | @specverse/entities | 5.4.1 | Entity modules (11 types, 9 facets), schema composition | | @specverse/engines | 6.37.0 | Toolchain — ./parser, ./inference, ./realize, ./generators, ./ai, ./bundles | | @specverse/runtime | 5.0.1 | Framework-agnostic view walker, React + Tailwind adapters, test-harness | | @specverse/assets | 1.17.0 | Pure content — prompts, examples, learning materials (no JS) |

Versions reflect the latest published to real npm. See CLAUDE.md for in-flight version landscape and what's new in each minor.

Quick Start

# Install globally
npm install -g @specverse/self

# Verify the install works end-to-end (60-90s, no flags or args needed)
spv smoke

# Initialize a new project (copies a template skeleton).
#   spv init my-app                          # default template (Category+Item
#                                            # canonical spec, ReactAppRuntime)
#   spv init my-app --template full-stack    # rich User/Project/Task demo
#   spv init my-app --template backend-only  # standalone API
#   spv init my-app --template frontend-only # standalone SPA
#   spv init my-app --static                 # ReactAppStarter — generated
#                                            # frontend is a fully standalone
#                                            # starter kit (no @specverse/runtime
#                                            # dep; editable source).
spv init my-app

# Generate the full application from the spec
cd my-app
spv realize all specs/main.specly -m manifests/implementation.yaml -o generated/code

# Build and run
cd generated/code
npm install && npm run db:setup
npm run dev

spv smoke — verify your install

Anywhere you can run npm install -g @specverse/self, you can run spv smoke to confirm the toolchain works end-to-end:

npm install -g @specverse/self && spv smoke

It spins up a throwaway project from the default template, realizes it, starts a backend, hits a CRUD round-trip, and tears down. If it prints New-user smoke test passed ✅ you're good. If it doesn't, the failing step + backend logs are printed in place — open an issue with that output.

A separate npm run smoke:static exercises the ReactAppStarter path (spv init --static) end-to-end: generates the standalone frontend, builds it with vite, and verifies belongsTo FK round-trips.

This works in any environment with Node 18+: a fresh laptop, a blank GitHub Codespace, a Docker container, a cloud shell.

npm run setup-variants — drive every flag combo locally

For interactive testing of all the spv init options simultaneously:

npm run setup-variants

Preps six side-by-side projects under tests/variants/:

| Variant | spv init invocation | Ports | |---|---|---| | v-default | (no flags) — Category+Item canonical spec | BE 3010, FE 5180 | | v-default-static | --static — ReactAppStarter | BE 3011, FE 5181 | | v-fullstack | --template full-stack — rich demo | BE 3012, FE 5182 | | v-fullstack-static | --template full-stack --static | BE 3013, FE 5183 | | v-backend | --template backend-only | BE 3014 | | v-frontend | --template frontend-only | FE 5184 → v-default's BE |

Each variant gets its own .env (unique ports) and run-dev.sh helper, so you can boot all six simultaneously without collisions. The output dir is gitignored — regenerate whenever.

init vs realize — two different commands

Important distinction that surprises new users:

• spv init <name> --template <t> — copies a skeleton from templates/<t>/ into a new directory. The skeleton contains specs, manifests, CLAUDE.md, package.json — but no generated code. It's a starting point.
• spv realize all ... — calls the engines to generate generated/code/ fresh from the current skeleton's spec and manifest. This is where the backend, frontend, CLI, VSCode extension, MCP server, diagrams etc. are actually produced.

The templates are live skeletons, not pre-baked projects. Every spv realize regenerates from scratch using whatever engine version is installed.

Available templates:

• default (implicit) — backend + frontend monorepo scaffold. Spec is the canonical Category + Item starter (shared with app-demo's Server Manager "new spec" action) — small enough to read in 30 seconds, rich enough to exercise the generated-UI rules (lifecycle dropdowns, belongsTo FK dropdowns, FK resolution in list/detail/dashboard).
• full-stack — same monorepo scaffold, but with the rich User / Project / Task demo spec (lifecycles, relationships, behaviors, events). Useful when demoing everything SpecVerse can do from one spec.
• backend-only — standalone Fastify + Prisma API. No frontend generated.
• frontend-only — standalone React SPA against an external API. No backend generated.

All four templates compile end-to-end with zero TypeScript errors and zero npm audit vulnerabilities.

--static is an orthogonal flag that works with any template: it pre-swaps the manifest so spv realize emits a ReactAppStarter frontend (fully standalone, editable source, no @specverse/runtime dep) instead of the default ReactAppRuntime (slim shell that loads views at runtime). Pick ReactAppStarter when you want to fork and customize the generated React; pick ReactAppRuntime when you want a thin generated surface you can regenerate freely without clobbering edits.

Repository Structure

specverse-self/
├── specs/
│   └── main.specly              # The self-specification (921 lines, 5 components)
├── manifests/
│   └── implementation.yaml      # Fastify + Prisma + SQLite + React + Commander.js
├── templates/                   # Skeletons used by `spv init`
│   ├── default/                 # Default — monorepo scaffold; spec loaded at
│   │                            # init time from engines' canonical default
│   ├── full-stack/              # Monorepo scaffold + rich User/Project/Task demo
│   ├── backend-only/            # Standalone Fastify+Prisma, no UI
│   └── frontend-only/           # Standalone React SPA, external API
├── bootstrap/
│   └── cli/                     # Frozen bootstrap CLI (promoted from generated/code)
├── generated/
│   └── code/                    # Current realize output (465+ files)
│       ├── backend/             # Fastify + Prisma, generated CLI, guards.ts
│       ├── frontend/             # React app (slim via @specverse/runtime)
│       └── tools/               # MCP server, VSCode extension
├── examples/                    # 54 composed examples from entity modules
├── scripts/
│   ├── compose-examples.mjs     # Compose examples from entity modules
│   └── indexing/                # Cross-repo content comparison tools
└── docs/
    ├── GOLDEN-RULES.md          # 41 permanent guiding principles
    ├── guides/                  # Architecture, entity, engine guides
    └── RELEASE-AUDIT-ACTIONS.md # 53 audit items, all resolved

Self-Specification Components

| Component | Models | Purpose | |-----------|-------:|---------| | SpecLanguage | 27 | The language itself — Specification, Component, Model, Controller, Service, Event, View, Deployment | | BuildSystem | 11 | Entity modules, convention grammars, inference rules, schema fragments | | ToolsSupport | 7 | VSCode extension, MCP server (generated via distributions entity type) | | AISupport | 2 | AI orchestrator, workflows | | CLI | 9 commands | validate, infer, realize, init, gen, dev, cache, ai, session |

CURVED Operations

SpecVerse uses CURVED, not CRUD:

• Create — instantiate a new entity
• Update — modify existing entity (full replace)
• Retrieve — fetch one or many
• Validate — check business rules without persisting
• Evolve — lifecycle state transitions (draft → open → closed)
• Delete — remove (soft or hard)

Custom actions sit alongside CURVED as POST /resource/:id/<actionName>. Generated controllers publish typed events (${Model}Created/Updated/Deleted/Evolved) for every CURVED operation that mutates state.

Attribute Category System

Every attribute is tagged at parse time with one of three categories so consumers don't fall back on name-based heuristics:

• business — user-facing domain data (title, price, status)
• metadata — synthetic/system fields (id, createdAt, updatedAt, version)
• relationship — foreign-key scalars for belongsTo relations

Forms hide metadata by default. List views colour-code relationship columns blue and lifecycle columns purple. This is set by AttributeProcessor/ModelProcessor during parse and flows through inference → YAML → realize without needing to re-classify.

AI Behavior Generation

Service operations and custom actions that can't be matched to a convention are handed to Claude via engines/src/ai/behavior-ai-service.ts. Each unmatched step becomes a pure TypeScript function emitted into behaviors/<ControllerName>.ai.ts and imported back into the controller at realize time. Prompts live under generated/code/prompts/core/standard/v9/; the current active set is v9.

Outputs are cached in .specverse/ai-cache/ keyed on sha256(step + model + operation + inputs + promptVersion) so re-running realize with unchanged steps is free.

Key Principles

See GOLDEN-RULES.md for the full 41 rules. Highlights:

• R8: Fix generators, never hand-edit generated output
• R11: Let engines handle their own initialization
• R12: Adding an entity type = 3 changes only
• R18: No version numbers in code identifiers
• R24: CURVED not CRUD
• R25: Engines live in specverse-engines, CLI orchestration separate
• R31: Bootstrap promote cycle is frozen — edit engine → realize self → test → promote

Related Repositories

| Repo | Purpose | |------|---------| | specverse-engines | 4 engine packages (types, entities, engines, runtime) — source of truth for all engine code | | specverse-app-demo | Dynamic runtime demo — interprets spec at runtime (complement to the static generation in this repo) | | specverse-lang-doc | Docusaurus documentation site |

License

MIT