Repository navigation
LiteSpec 2.0.0
LiteSpec 2.0.0 is the standards contract for one bounded-context business application, built by people and agents. People and agents write intent records; the model builder reads the code, screens, tests, and test runs and computes the links between the two. A consumer installs this release as the LiteSpec.Cli local .NET tool at the release version, records it in reviewedLiteSpecVersion, and keeps it for as long as it serves. The release takes effect as the v2.0.0 tag.
Structure
- The folder a page sits in decides who applies it.
core/,workspace/andquality/apply to every project. Pages directly inbackend/andfrontend/are the principles every backend and every frontend follows. - A stack is a folder inside its area:
backend/dotnet/,frontend/web/react/,frontend/web/svelte/andfrontend/blazor/. Selecting a stack applies its folder and every folder above it, sofrontend/web/holds the TypeScript web pages React and Svelte share. - A deeper page, an extension's
replaces, or a project deviation record replaces a named provision of a shallower page. - An extension for every stack sits in
ext/; an extension for one stack sits in that stack'sext/folder, such asbackend/dotnet/ext/efcore.md. Extensions ship for outbox, tenancy, plans, audit, caching, realtime, jobs, stage and delegation, among others. - A provision ID is its page and heading:
litespec/<page>#<slug>, such aslitespec/backend/dotnet/domain#model-every-closed-set-of-domain-values-without-enums. Headings carry no ID; the ID, the file and the published address follow one rule.docs/reference/provisions.mdlists every provision with its verification mark. - Pages follow the page contract in
docs/core/authoring.md: ASCII only, one term per concept, capitalized modals only inside a Statement, a Default or a Replacement, Title Case on every heading, anOverviewtitle on every section index, and nothing about other releases. LiteSpec writes US English. - Every provision is marked
checkable, naming the command that checks it and the finding it reports, orguidance, naming the observable evidence and where to look.
Selection
- A project names a size, a shape, and its stacks in
litespec.project.json. Size issmallorlargeand decides the record types and test projects. Shape isserver, with one backend stack, orclient-only, with none, which applies the backend architecture, domain, application and identifier principles. litespec init --preset dotnet-react|dotnet-svelte|blazor-client --size small|largewrites a startinglitespec.project.json. A preset adds no rule.- The
LiteSpec.Clipackage carries the whole release beside its binary: the manifest, schemas, docs, and templates, so a consumer needs no checkout of this repository.litespec initwrites.config/dotnet-tools.jsonpinning the tool at the release and fills the## LiteSpecblock ofAGENTS.mdwith the release, size, shape, stacks, and selection index of the new project. - A departure from a rule is a deviation record with its reason and review date. A finding the project accepts for now is a known gap record with an owner and an end date.
Records and the Model
docs/core/model.mddefines the record types, each answering one question: product, goal, problem, feature, constraint, research, decision and requirement for why; journey for the steps toward one goal; module, aggregate, rule, event, use case, result and scenario for how the business works; actor, role, permission, entry point and external system for who acts and how they arrive; limit and runbook for operation; deviation, known gap and glossary term for how the project builds and speaks.- Every record carries an owner and a status of draft, approved or retired. A draft names its decider and decide-by date, an approved record is replaced rather than edited, and only a decision carries
replaces. - Identifiers use the
type/home.nameform, chosen by a person and stable once approved. - An aggregate names its states, the transitions between them, and its classified data. A rule is an invariant, a precondition, a calculation or a cross-aggregate rule. A use case is a command, a query or a reaction, and carries its input and output. A result is a success or a refusal with a stable code. A scenario states its given, when and then, with an optional examples table.
- A requirement is functional, quality or business, and names the feature that delivers it. A measured quality requirement carries its measure, target, conditions, check and evidence.
- The builder computes implemented, verified and reachable over the records, and the effective status of each record.
docs/core/product.mdplaces business intent in a product brief and requirement pages,docs/core/domain.mdstates the domain records, anddocs/core/access.mdstates who may act and how each use case is reached. - An
ownersentry maps a readable owner name to its CODEOWNERS handles, andlitespec model checkreportsowner-unknownfor a record whose owner, directly or through its mapped handles, belongs to no team owning its path. - The model builder reads a refusal code where code declares one: a
Codemember of an exception, failure, or refusal type, an exception constructor argument, or a value namedcode. Any literal counts as evidence that a recorded code is thrown, and a rule's barerefusalcode declares a guard no caller reaches because an earlier check refuses first. - A rule that governs an aggregate and an erasure or export use case in another module covers that aggregate's personal data.
- Events link by their natural name (
AccessCodeIssuedEventisevent/access-code.issued) or by the record id the event class states. Reactions and jobs link through an<implements>tag or the use-case folder that holds them, an endpoint that holds its behavior implements its use case, and a creation row (-in From) reaches its state.
The Command Line
- One .NET 10 command line,
litespec, withvalidate,provisions,consumer,ui,model,book,initandpatterns. The reporting commands take--root <path>and--format json, and every command writes UTF-8 with\nline ends on every platform. litespec model buildwritesmodel.jsonwith the computedimplements,callsandproveslinks;checkreports open findings and expired known gaps;renderwrites the generated page regions;queryprints one record with its links both ways;diffreports the records a change adds, changes and removes for review. It reads C# through Roslyn, React and Svelte routes, and TRX or JUnit XML test results, each stack through its own reader.litespec bookgenerates the project book, a static site with one page per record, an index per type, a lens per actor, a review page, a glossary and search.litespec consumerchecks the project file, the selection of size, shape, stacks and extensions, every record page againstschemas/record.schema.json, and the project vocabulary.litespec uichecks the controlled web UI contract.litespec consumervalidates a large consumer in seconds: it reads pages and source surfaces in parallel and reports findings in a fixed order.litespec validateandlitespec provisionscheck this repository's own pages, schemas, manifest and provision index.litespec patternsdraws the UI pattern wireframes for a person to choose from.previewwrites one offline page with every option at desktop and phone width,svgprints one option, andcheckreports broken wireframes.
Analyzers
LiteSpec.Analyzersis a NuGet package of Roslyn analyzers that report a breach of a .NET provision as an error in the editor and the build, each diagnostic linking to its provision. Rules cover Domain (outer-layer references, closed value sets, state records, Domain exceptions, events and their placement, binary floating point, clock and random reads, repositories, documentation, and typed identifiers), the outer layers (implementation shape, handler and endpoint naming, reactions and jobs), naming and style, and one assertion rule for test projects.- A rule runs only in the layers its provision covers. The layer comes from the
LiteSpecLayerMSBuild property or the assembly name suffix. The package runs on the .NET 9.0.300 SDK, Visual Studio 17.14, and later. docs/backend/dotnet/packages.mdadds the convention to reference the package from the five application projects, the manifest pins it, and the rules the analyzers check completely are markedcheckable.
The Site
- litespec.dev publishes every page of the release for people, with a navigation tree, provision cards, highlighted code, tabbed UI pattern options with a full-screen viewer, search, and light and dark themes.
- Agents read
/llms.txt, a raw Markdown copy of every page, one index per selection of shape and stacks, one bundle per layer, and the schemas./latestredirects to the current release. docs/learn/holds explanation pages that teach what LiteSpec is, why it exists, and how its parts and tools fit together, among them the reading tracks and the lineage of borrowed practices.
UI Patterns
- A pattern page in
docs/frontend/patterns/answers one group of recurring interface questions. Each pattern names its question, its default option, its compact behavior and its rationale. Each option carries a wireframe in a closed text language, its rationale and its cost. - The wireframe language, defined in
docs/frontend/patterns.md, states structure and real copy, never style. An agent builds an option in its own stack and design system. A pattern ID islitespec/frontend/patterns/<group>#<pattern>. - Ten groups ship: page frames, lists and tables, record detail, forms and fields, dialogs and overlays, create, edit and remove, feedback and states, navigation, money, time and density, and admin screens. A project catalog cites a pattern by its ID in
library.
Pins
litespec.manifest.jsonpins the .NET 10 workspace (ASP.NET Core 10.0.13, Marten 9.50.1, Aspire 13.6.1, OpenTelemetry 1.19, Testcontainers 4.16.0, LiteBus7.0.0-preview.6), xUnit v3 on Microsoft.Testing.Platform with Reqnroll and LightBDD, and the web toolchain (Node 24.22.0, pnpm 11.28.5, Vite 8.3.4, TypeScript 6.0.3).- Every schema's
$idis its address on the published site:https://litespec.dev/2.0.0/schemas/<file>.
Releases
- A
v<version>tag publishesLiteSpec.CliandLiteSpec.Analyzersto nuget.org, creates the GitHub release from this section, and deploys the site.