All pages in 2.0.0

Learn LiteSpec

These pages explain what LiteSpec is, why it exists, and how its parts fit together. Read them in order the first time. They state no rules of their own: the rules are on the standards pages they link to.

Why LiteSpec Exists

This page explains the problem LiteSpec solves and the approach it takes. Read it if you're deciding whether LiteSpec fits your team.

How LiteSpec Works

This page follows one use case from its written record to its code and back, to show how LiteSpec's parts fit together. The example is a small library system, the same one the model builder's own tests use.

Read the Standard

This page explains how the standard is organized, so you can find the rules that apply to your project and read a rule the way it's meant.

Records and the Project Model

This page explains what a LiteSpec project writes down, where it keeps it, and what the model builder works out from it. The exact record types, fields, and links are on the model page.

How the Tools Fit Together

This page shows the three tools LiteSpec ships, the job each one does, and the order you run them in when you change a consumer project. The running example is a team building a small shop: shape server, stacks dotnet and react, size small, with one React frontend named web at apps/web.

How LiteSpec Compares

Spec-driven development means writing down what to build before an AI coding agent builds it. This page compares LiteSpec with ten other approaches: per-feature workflows, team standards systems, instruction files, behavior examples, architecture documentation, and architecture tests. These facts were read on the official pages on 2026-10-21.

Work with Agents

This page explains how an AI agent uses LiteSpec in your project: how it finds the rules, what it may decide on its own, and what it brings back to you. The exact rules are on the agent page.

Adopt LiteSpec

This page describes what adopting LiteSpec involves for a team, in the order teams usually do it. For the exact steps on a new repository, follow Get started.

Agent Operating Protocol

This protocol controls how agents select context, resolve standards, preserve user work, and report completion. Agents query the project model for the records a task needs and read the generated agent context first.

Authoring Standard

This page states how LiteSpec pages and consumer specification pages are written: the page styles, the provision contracts, the identifiers, the verification table, and the prose style. Prose follows the Google developer documentation style guide, with the few additions this page states. The structure rules are what litespec validate and litespec consumer check.

Maintaining the Standards

This page is the maintainer's manual for the LiteSpec repository itself. It states how a provision moves through its lifecycle. It states how an identifier rename is handled. It states how citations are written. It states how a LiteSpec release is published.

The Project Model

Every project describes itself with records of fixed types joined by fixed links. People and agents write the intent records. The builder reads the code, screens, tests, and test runs, and computes the links between the two.

Engineering Principles

These principles resolve choices no narrower rule covers. They favor explicit intent, proven behavior, and evidence over speculative abstractions.

Product Intent

This page governs where a consumer states its business intent and in what form. Business intent is what the product commits to as a business. It covers what the product sells, to whom, at what price, and in which markets. It also covers how the company runs and what comes next.

Release Standard

A release joins deployed product behavior with evidence that a maintainer can operate it. One completed layer or passing test category does not meet this outcome.

Supported Scope

Every project selects one size, one shape, and its stacks, so agents can make concrete decisions without inventing architecture for every task. A stack applies the pages in its own folder and in every folder above it; a preset only fills in a common selection.

Stacks

A stack is one technology's binding of the specification, held in one folder: a backend stack under backend/, a frontend stack under frontend/. Selecting a stack applies its folder and every folder above it, so a stack never restates an inherited principle (Supported scope). Each stack folder holds a stack.md that states what the stack adds: its rules, its version pins, and its checks. These rules govern every stack selection.

LiteSpec

LiteSpec coordinates software work with agents as active engineering participants. It combines records, architecture standards, agent protocols, implementation conventions, tests, operating controls, and release records.

Configuration

Repository configuration should make builds repeatable and fail before a deployment starts with missing or invalid values. Version pins, compiler rules, environment access, and secret handling have one defined owner.

Dependencies

Layer dependencies and package ownership make the application boundary visible to review. Each layer accepts only the dependencies its owning provisions allow, and each project rejects packages introduced without a current requirement.

Naming and Code Style

Names should expose business intent and architectural role without requiring a reader to open the file. Fixed suffixes and file conventions reduce variation across agent sessions.

Workspace Structure

One canonical monorepo tree lets agents locate applications, shared packages, documentation, and tests without searching for a project-specific interpretation. The structure supports an API-only application, one frontend, or multiple frontends while retaining one bounded context.

HTTP API

WebApi is a thin transport adapter. It maps HTTP input to Application messages, dispatches through the specific mediator, and maps results to stable HTTP contracts. Business rules, persistence access, and provider behavior remain outside endpoints.

Application Layer

Application coordinates use cases. It translates a command or query into Domain and persistence work, applies structural input validation, and returns a transport-neutral result. It does not contain HTTP behavior or provider implementations.

Backend Architecture

The backend is a five-part modular monolith. Part boundaries separate business rules, the contracts every layer names, use-case coordination, technical adapters, and HTTP hosting. They do not split each concern into a deployable unit.

Domain Layer

Domain holds the business model and protects aggregate invariants. It references no persistence, HTTP, messaging, logging, configuration, injection, serialization, or provider concept. Its names match the Terms that its records use.

.NET HTTP API

The .NET backend maps each HTTP operation through one endpoint class and generates its OpenAPI contract at build time. The shared provisions live on the stack-neutral page (HTTP API); this page holds what the dotnet stack alone requires.

.NET Application Layer

Application code in a .NET backend dispatches through LiteBus mediators and reports LiteBus validity. The shared provisions live on the stack-neutral page (Application Layer); this page holds what .NET alone requires.

.NET Architecture

Architecture in a .NET backend is five projects with explicit composition roots. The shared provisions live on the stack-neutral page (Backend architecture); this page holds what dotnet alone requires.

.NET Configuration

Configuration in a .NET backend pins the SDK, build settings, packages, and tools through MSBuild files. The shared provisions live on the stack-neutral page (Configuration); this page holds what .NET alone requires.

.NET Domain

This page states how the dotnet stack realizes the Backend domain rules (Backend domain). It lists the C# types, project references, and tooling one dotnet Domain project requires. Each provision here cites the stack-neutral rule it realizes.

Executable BDD Acceptance Tests

This extension adds executable scenarios for critical cross-layer examples. A consumer writes them as Reqnroll Gherkin features with C# step definitions or as LightBDD feature classes. The use-case specification remains the authored behavior source.

EF Core Persistence

This extension states the Entity Framework Core form of the read, query and mapping rules. It applies to aggregates with accepted relational navigation, change-tracking, or provider requirements that the baseline provider cannot satisfy.

.NET Naming and Code Style

Names in a .NET backend follow C# file, asynchronous method, and implementation style rules. The shared provisions live on the stack-neutral page (Naming and code style); this page holds what the .NET stack alone requires.

.NET Packages

A .NET backend realizes package boundaries with project references and NuGet central management. The shared provisions live on the stack-neutral page (Dependencies); this page holds what .NET alone requires.

.NET Persistence

Marten is the baseline provider for persistence. The shared provisions live on the stack-neutral page (Backend persistence); this page holds what the .NET stack alone requires.

.NET Stack

This stack binds the backend to .NET. The specification states each backend and workspace principle. The pages in this stack's folder state how a .NET backend realizes it. The model builder reads C# code, C# scenarios, and test results for the backend.

.NET Testing

Tests in a .NET backend run in the test projects the size requires, through xUnit, WebApplicationFactory, and one shared harness. The shared provisions live on the stack-neutral page (Backend testing); this page holds what the .NET stack alone requires.

.NET Workspace

A .NET backend realizes the workspace tree with solutions and project files. The shared provisions live on the stack-neutral page (Workspace structure); this page holds what .NET alone requires.

Record Identifiers

Every record carries one identifier naming its type, home, and name. One form per type lets a reader find the record from the identifier alone, by reading or by searching.

Persistence

This page states how the backend stores and reads aggregates. Commands load and stage aggregates through Domain-owned repositories. Queries read through the session directly in Application, because the selected stack treats document queries as an explicit read-side dependency.

Backend Testing

Backend tests prove Domain behavior, use-case coordination, real persistence and HTTP integration, and structural architecture at separate boundaries. A test that calls the use case and asserts its result proves each Case of a use case.

Browser Persistence

Browser storage is the only durable store in a client-only product. It is small and shared, and it can disappear. Access runs through one adapter, keys carry versions, and shapes migrate. The user can always export what they made.

Blazor Components

This page holds how the Blazor stack realizes the frontend component principles (Frontend components). A client component renders what it is given and reports what the user did. Business rules stay in Domain and Application, browser access stays behind an interface, and each file holds one component.

Blazor Data and State

This page holds how the Blazor stack realizes the frontend data rules (Frontend data). Every use case runs through Application. State carries a declared classification, loads once at startup, and reports failure explicitly rather than through an absent value.

Blazor Rendering and Routes

The client renders entirely in the browser. Routes declare their own templates and states, the acquisition surface stays outside the runtime, and the application keeps working after the network goes away.

Blazor Stack

This stack serves a product that has no server of its own. It combines a .NET client-side domain model, browser-local persistence, and a Blazor WebAssembly application compiled to static output. Such a product declares the client-only shape under litespec/core/scope#declare-a-consumer-that-has-no-backend, which names the backend pages that still apply. This page adds what Blazor itself requires. Exact framework and package versions live only in litespec.manifest.json.

Blazor Structure

The client is one Blazor WebAssembly application organized around the same business modules and use cases as the Domain. Pages compose features, feature folders own behavior, and shared folders hold only code with real cross-feature use.

Blazor Testing

This page holds how the Blazor stack realizes the frontend testing principles (Frontend testing). The client has four test projects matching its four boundaries. Core tests run without a browser, component tests substitute interop, and a small browser suite proves the behavior only a real browser can show.

Frontend Components

One shared UI package holds everything a page draws with. It holds the shared primitives and the composites those primitives are assembled into.

Frontend Data and State

The frontend holds no contract of its own. It calls the API through one generated client, reads every answer through its cache, and sends each write as a command.

Admin Screen Patterns

Admin screens configure the back office itself. They cover the team and its roles, API keys and webhooks, data imports, the payment account, supplier invoices, and discount codes. These patterns answer how each screen is laid out. Each pattern offers drawn options and names a default.

Create, Edit and Remove Patterns

These patterns answer how a reader creates a record, changes one that exists, removes one or several, and changes something that has already happened. Each pattern offers drawn options and names a default.

Dialog and Overlay Patterns

An overlay sits above the page: a dialog, a drawer, a popover, a menu, a toast, or a bar that stays in view. These patterns answer when each one fits and how it opens, holds focus, and closes. Each pattern shows its options as wireframes and names a default.

Feedback and State Patterns

A screen spends part of its life empty, loading, refused, offline, or failed. These patterns answer what shows in each of those states and how a command reports that it worked. Each pattern offers drawn options and names a default.

Form and Field Patterns

A form collects values you enter to create or change a record. These patterns answer how each kind of field takes its value and how a form reports a refused submit or unsaved work. Each pattern offers drawn options and names a default.

List and Table Patterns

A list or a table shows many records of one kind, so a reader can find, compare, and act on them. These patterns answer how columns, sorting, filters, selection, paging, and the states of a table behave. Each pattern offers drawn options and names a default.

Money, Time and Density Patterns

These patterns answer how a back office writes amounts, statements, moments, and periods. They also answer how many rows fit before a page breaks and how figures and charts read. Each pattern offers drawn options and names a default.

Navigation Patterns

Navigation is the frame around every page: the sidebar, the header, the breadcrumb, tabs, the command palette, and the account menu. These patterns answer how a reader moves through the back office and knows where they are. Each pattern offers drawn options and names a default.

Page Frame Patterns

A page frame is the layout of one kind of page. It covers a home page, a list, a queue, a record, a form, a report, a settings page, or an outcome. These patterns answer how each kind of page is laid out. Each pattern offers drawn options and names a default.

Record Detail Patterns

A record detail page shows one business record, such as an order, a customer, or a product. It shows its state, its facts, its history, and the commands a reader may run on it. These patterns answer the recurring questions of that page. Each pattern offers drawn options and names a default.

UI Pattern Decisions

Every recurring interface question is decided once and recorded in one catalog. Each entry holds the options considered, the option chosen, the compact-screen behavior, and the implementation per platform. Implementers build from the chosen option and extend the catalog rather than redrawing the pattern.

Frontend Rendering and Routes

A route answers three questions: what address is this, what data does it need, and which floorplan draws it. Everything else belongs in a module.

Frontend Structure

A frontend holds three parts: a frame, routes, and use-case modules. The frame holds everything cross-cutting. The routes hold the addresses the frontend serves. The modules hold one folder per backend use case the frontend calls. Each frontend is one entry-point record.

Frontend Testing

Frontend tests prove behavior at the cheapest boundary that represents the risk. Each kind in the table below runs against a frontend, and each one answers one question.

Controlled UI Governance

The shared UI package is a constrained construction language. It provides the primitive source, the interaction behavior, the layout, and the tokens. A route names one floorplan and fills its slots from the domain. A route suite proves every route.

TypeScript Web Components

This page states how the TypeScript web stacks realize the frontend component principles (Frontend components). It states the registry source, the closed element list, and the visual file patterns. It also states the raw HTML sinks and the route suite checks the React and Svelte stacks share.

Web Data and State

This page states how the TypeScript web frontends realize the Frontend data rules (Frontend data). It states the generated client, the query cache behavior, and the tooling the React and Svelte stacks share. A provision here cites the neutral rule it realizes.

Web UI Pattern Decisions

This page states how the TypeScript web group realizes the frontend pattern rules (UI Pattern Decisions). It states the React and Svelte bindings and the widths one web implementation requires. A provision here cites the neutral rule it realizes.

React Components

Components in a React frontend are function components with typed boundaries. The shared provisions live on the stack-neutral page (Frontend components). This page states what React alone requires.

React Stack

This stack serves a React frontend beside the product's backend stack. A React frontend takes one of three rendering modes, chosen by who reads it. An authenticated console is a static single-page application. A public surface whose pages are shared as links and read by a search engine renders on the server. A device client that asks one question repeatedly is a static page with no router. The shared stack rules on the Stacks page apply to every stack.

Web Rendering and Routes

This page states how the TypeScript web stacks realize the frontend rendering rules (Frontend rendering). It states the loaders, queries, router files, and tooling the React and Svelte stacks share. Each realization cites the neutral rule it follows.

Web Structure

This page states how the TypeScript web stacks realize the Frontend structure rules (Frontend structure). It states the toolchain, folders, and commands the React and Svelte stacks share. A provision here cites the neutral rule it realizes, where one exists.

Svelte Components

Components in a Svelte frontend hold state in runes with typed boundaries. The shared provisions live on the stack-neutral page (Frontend components). This page states what Svelte alone requires.

Svelte Stack

This stack serves a Svelte frontend beside the product's backend stack. A Svelte frontend takes one of three rendering modes, chosen by who reads it. An authenticated console is a static SvelteKit application. A public surface whose pages are shared as links and read by a search engine renders on the server. A device client that asks one question repeatedly is a static page with no router. The shared stack rules on the Stacks page apply to every stack.

Web Testing

This page states how the TypeScript web stacks realize the frontend testing principles (Frontend testing). It states the runners, libraries, and commands one web frontend requires. A provision here cites the neutral rule it realizes.

Web UI

This page states how the TypeScript web stacks realize the frontend UI rules (Frontend UI). It states the toolchain, registry, tokens, and suites one web frontend requires. A provision here cites the neutral rule it realizes.

Continuous Integration

Continuous integration proves that a pull request preserves the selected standards, generated contracts, dependencies, and release artifacts. The workflow keeps slow deployment checks separate from fast local feedback while retaining one required merge gate.

Operations

A released application is observable, deployable, recoverable, and supportable by one maintainer. Operating behavior is part of the use-case slice when code changes schema, external dependencies, background work, or failure recovery.

Security

Security boundaries follow identity, resource ownership, data classification, and trust transitions across API, persistence, frontend, external services, and operations. Authentication establishes identity. Each use case declares the permissions it needs, and the application guard authorizes from them.

Extensions

Extensions add conditional standards to the baseline stacks. An extension stays inactive until a current requirement meets its activation criteria. The consumer lists its ID in selectedExtensions within litespec.project.json, with the criterion it met and a review date.

Audit Trail

An audit trail is evidence that one actor attempted one action against one target, and what the attempt produced. It answers who is accountable.

Caching

Caching trades freshness and invalidation work for lower latency or source load. This extension requires measurement, a named staleness contract, and a recovery path.

API Compatibility

OpenAPI freshness proves that committed artifacts match source code. It does not prove that independently deployed consumers can continue using the API.

Concurrency and Idempotency

Concurrency control protects invariants when accepted writes overlap. Idempotency protects an operation from duplicate execution after a retry or uncertain network response.

Container Deployment

This extension defines image and rollout requirements for hosted environments that deploy immutable images. It supplements baseline release and operations standards.

Agent Delegation

One agent can hold a whole change in view. A fleet cannot hold it. Delegation needs written boundaries where one agent needs none. This extension states the brief, the containment, and the acceptance check.

External Integrations

External systems are unreliable and outside application change control. This extension keeps provider details in Infrastructure, maps failures to project-owned outcomes, and tests network boundaries.

Scheduled Jobs

Scheduled work runs independently of HTTP requests and remains safe when replicas restart, overlap, or lose connectivity. This extension covers recurring and delayed jobs, not durable event dispatch.

Data Lifecycle

Retention, deletion, archival, and restore behavior follows the business and legal lifetime of data. This extension makes lifecycle work explicit without imposing soft delete.

Localization

Localization makes routes, messages, formatting, metadata, and tests locale-aware while stored Domain values remain locale-neutral.

Model Context Protocol

An MCP server presents the product's API to an LLM client running outside the product. The API provisions own the behavior the server calls. This page states how the server presents itself, describes its tools, and words its refusals.

Outbox Worker

The outbox makes a business commit and its required outgoing message durable in one database transaction. A Worker dispatches pending records with retry, idempotency, visibility, and safe replay.

Realtime Updates

Realtime transport reduces visible update delay when polling cannot meet an accepted user requirement. Messages remain refresh hints unless a use case defines durable ordered delivery.

Reporting and Exports

Reporting separates complex joins, aggregate analysis, and large exports from normal request projections when cost or duration exceeds the baseline read path.

Static Marketing Site

A static marketing site presents the product to the public as pages that need no server. It serves people, search engines, and language models from one build.

Release Stage

A consumer passes through two release stages. Before the first deployment holds customer data, several provisions assume a service that does not exist yet. This extension declares the stage, bounds what the early stage defers, and records the promotion that ends it.

Multitenancy

Multitenancy makes tenant identity part of authorization, persistence, caches, jobs, exports, diagnostics, and recovery. A tenant ID column alone does not provide isolation.

Get Started

This tutorial starts a consumer repository at small size. At the end the repository holds its configuration, its first records, one implemented use case, and a passing model check. Where a step differs by stack, run the row that matches the stacks in litespec.project.json.

Model a Domain Module

This tutorial models one domain module that the model builder reads. At the end the module holds its language, its business records, its rules, its use cases, its events, and its permissions. The worked example is the circulation desk of a library.

Build an Audit Trail

Build the audit trail that the audit extension requires, on the LiteBus command pipeline of the .NET stack.

Check .NET Code with the Analyzers

Run the LiteSpec Roslyn analyzers over your .NET backend so every build reports the findings that break LiteSpec rules, and fix or record each finding.

Standards Commands

Each page here documents one command the repository ships: its arguments, its options, its exit codes, and what it runs underneath.

Book

litespec book generates the project book, a static website that reads a consumer's model.json, so a founder or reviewer reads the project model as linked pages.

Validate Consumer

litespec consumer holds a consumer repository to the release it pinned.

Initialize Consumer

litespec init starts a consumer repository from a ready-made preset.

Model Builder

litespec model builds the project model, checks it, renders generated regions, and answers record queries.

Draw Patterns

litespec patterns draws, prints and checks the wireframes on the UI pattern pages.

Generate Provisions

litespec provisions writes the provision index that resolves every identifier to its page.

Validate Controlled UI

litespec ui holds an opted-in consumer with a controlled web frontend to the UI contract.

Validate Standards

litespec validate holds the LiteSpec repository to its own authoring contract.

Analyzer Rules

When you get an LS diagnostic from the LiteSpec.Analyzers package, this page tells you exactly what the rule checks, why the standard requires it, and how you fix the code. When you review a finding, this page tells you what the rule ignores, so you can decide whether the finding is a false positive.

Audit Obligations

This page states the external obligations that the audit extension satisfies. It is informative. The extension page owns every provision.

Decision Records

A decision record states one choice that is expensive to reverse, with the options weighed and the evidence cited. This page states where the record lives, what it holds, and how it ends.

Glossary

Release Manifest

You read litespec.manifest.json when you maintain the LiteSpec release itself: it lists the stacks, shapes, extensions, and version pins the release ships. You never edit it in a consumer project; your consumer pins the whole release and records the version you reviewed in litespec.project.json. This page lists every field the manifest holds with the real values of the current release, states what each field drives, and states how you add a stack or an extension.

Project File

You keep litespec.project.json as the one record of what your consumer project selected: its size, shape, stacks, extensions, owners, paths, and pinned release. You edit this file when your selection changes, and you validate it with litespec consumer before you rely on it. This page lists every field the file holds, what reads each field, and the errors you meet when a value is wrong.

Provisions

Use this generated page to resolve a provision ID to its heading, owning page, and verification mark.

Published URLs

An agent wires itself to LiteSpec through URLs on https://litespec.dev, not through a local checkout. This page lists every URL the site serves for agents and people: its pattern, a real example for the current release, and what it returns.

Schemas

A schema states the exact shape of one JSON file a tool reads, so a validator and an editor check the same contract. This page lists every schema the release ships, with the file it validates, the command that checks it, its published URL, its top-level properties, and a real example.