---
name: specverse
description: User-facing skill for SpecVerse — authoring `.specly` files, analysing existing codebases into specs, and orchestrating code generation via the `spv` CLI. Use when the user mentions SpecVerse, `.specly` files, the `spv` CLI, the `@specverse/*` packages, or wants to create / analyse / realize specs interactively. NOT for the engine-internal LLM emit step (see `realize-emit` for that — it's a separate skill that the engines pipeline auto-loads when emitting `.ai.ts` files).
---

# SpecVerse

SpecVerse is a declarative specification language. You describe **WHAT** a system does in a `.specly` file, and the engines generate **HOW** — backend (Fastify + Prisma), frontend (React + Tailwind), CLI, tools (VSCode extension + MCP server), and architecture diagrams.

**Core principle:** Define Once, Implement Anywhere. One spec, many realized targets.

## How to use this skill

1. **Ground yourself first.** Before authoring or editing a `.specly`, read `reference/ai-guidance.yaml` (curated LLM hints on what valid specs look like) and `reference/minimal-example.specly` (a concrete minimal spec exercising every feature). The schema itself is in `reference/schema.json` (JSON Schema draft 2020-12). Task-specific guidance lives in the `workflows/` flow for your task (next step) — there is no monolithic guide; grounding is scoped per task.
2. **Pick the right workflow.** The `workflows/` directory contains the canonical task flows, each carrying its own scoped guidance. Read the relevant one before starting.
3. **Don't invent syntax.** Every attribute, relationship, lifecycle, controller operation, view, event, manifest entry, and deployment instance is declared by the schema. If something isn't in the schema, it doesn't belong in a `.specly`.
4. **CURVED, not CRUD.** Controllers use six operations: **C**reate, **U**pdate, **R**etrieve, **V**alidate (dry-run), **E**volve (lifecycle transition), **D**elete. Validate and Evolve are the things that distinguish SpecVerse from an ORM scaffolder.

## Workflows (`workflows/*.md`)

| Workflow | When to use |
|---|---|
| `create.md` | Natural-language requirements → minimal `.specly`. Start here for new specs. |
| `analyse.md` | Existing codebase → `.specly` that captures what is implemented (reverse-engineering). |
| `materialise.md` | Turn a `.specly` into a complete production codebase (components + deployments + manifests → runnable code). |
| `realize.md` | Generate environment-specific deployment configs (dev/staging/production manifests) from a spec. |
| `behavior.md` | Generate a pure TypeScript function body for a single spec behavior step that doesn't match a convention pattern. |
| `app-demo.md` | Interactive spec creation/modification for the app-demo runtime interpreter (COMPLETE specs, not minimal ones). |

## The toolchain (`spv` CLI)

After the user runs `npm install -g @specverse/self`, the `spv` command is available. Key subcommands:

- `spv init <name>` — scaffold a new project (templates: default, full-stack, backend-only, frontend-only)
- `spv validate <spec>` — parse + schema-validate
- `spv validate-bundle <dir>` — validate an entity bundle (for engine extenders)
- `spv infer <spec>` — expand a minimal spec to full architecture (controllers / services / events / views)
- `spv realize all <spec>` — generate production code from inferred spec + manifest
- `spv ai template <op> <spec>` — dump a standard workflow prompt filled in for a specific spec

Full CLI reference in `reference/cli-reference.md`.

## Three-layer architecture

- **Components** (WHAT) — models, controllers, services, views, events. Technology-agnostic. Business logic lives here (`requires` / `ensures` / `steps` / `publishes`).
- **Deployments** (WHERE) — environment-specific operational policies (transactions, retries, rate limits, autoscaling).
- **Manifests** (HOW TO BUILD) — capability → instance-factory mappings that select technology (Fastify vs. NestJS, Prisma vs. TypeORM, etc.).

Swap the manifest to change the tech stack; the spec doesn't change.

## Authoritative references (in `reference/`)

- `schema.json` — the JSON Schema (draft 2020-12). Ground truth for what's valid.
- `ai-guidance.yaml` — schema annotated with LLM hints and examples.
- `minimal-example.specly` — one complete minimal spec showing every feature.
- `cli-reference.md` — every `spv` subcommand with flags + arguments.
- `workflows/*.md` — per-task flows, each carrying its own scoped grounding (the canonical user guide is the human-facing `docs/guides/` set, not bundled here).

## Anti-patterns to avoid

- **Don't hand-edit generated code.** The generators own it. Change the spec or the manifest; regenerate.
- **Don't use CRUD terminology or 5-op controllers.** CURVED has 6 operations for a reason — Validate and Evolve are load-bearing.
- **Don't invent package names.** `@specverse/deployments/*` / `@specverse/domains/*` (as if they were npm packages) are a historical fiction — spec libraries are loaded via `imports:` inside a `.specly`, not installed from npm.
- **Don't fill `specVersion` with `3.x` or `4.x`.** Current schema is `5.0.0`.