How the Tools Fit Together

Intent#

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.

The three tools#

LiteSpec ships one command line, one set of .NET analyzers, and one published site. Each one serves a different reader.

The command line#

The litespec CLI reads records, code, and configuration and reports what it finds. The command index lists every command with its arguments, options, and exit codes. You run repository commands with dotnet run --project apps/cli/src/LiteSpec.Cli -- <command> from the LiteSpec checkout, or with dotnet run --project litespec/apps/cli/src/LiteSpec.Cli -- <command> from a consumer that pins LiteSpec at litespec/. The pages write both forms as litespec <command>.

The CLI finds its LiteSpec checkout above its own binary. You point it at another checkout with LITESPEC_HOME, and you print its release with litespec --version.

The analyzers#

LiteSpec.Analyzers checks your .NET code while you type and while it builds. You add the package once, and each warning names the provision it enforces and links to it. The how-to guide shows the setup, and the analyzer reference documents every rule with its breach and compliant shapes.

The published site#

litespec.dev publishes the release you pinned. You read it as HTML in a browser. An agent reads the same release as plain text through the selection index and the raw page URLs, as Work with agents describes.

One change from start to finish#

Say the shop team adds a use case that lets a reader borrow a copy of a book. The change moves through the tools in this order.

The diagram below shows where each tool runs in that one change.

1. Start the project once with litespec init --preset dotnet-react --size small. The command writes litespec.project.json with shape server, stacks dotnet and react, and one frontend web at apps/web, stamped with the reviewed release. It never overwrites an existing project file. The init page lists the three presets and their selections.
2. Write the records. You add a product brief, a module, business records, and the new use case with its results, each as a short page with a JSON header. The templates/consumer/ folder of the release holds a starting file for each type. Records and the project model explains what the team writes down.
3. Choose the interface. For each recurring interface question, LiteSpec offers drawn options and a default. You draw them locally with litespec patterns preview <group>, pick one with the team, and record the choice in your pattern catalog. The patterns page describes the preview, svg, and check subcommands.
4. Validate the records with litespec consumer. The command reads litespec.project.json and every page under your documentation root, checks the project record, the stacks and extensions, each page header, the language record, and the controlled web UI contract. The consumer page lists what it reads, and the controlled UI page lists what the UI check covers.
5. Build the code to the standard. The handler lives in the Application project in a folder that mirrors the record, and the analyzers flag slips as you work. If you model a closed set of values as an enum, the build reports LS1002 and points at litespec/backend/dotnet/domain#model-every-closed-set-of-domain-values-without-enums on the domain page, which shows the record hierarchy that replaces the enum.
6. Compute the model with litespec model build. The builder reads your records, the backend code, the frontend routes, the acceptance scenarios, and the latest test run, and writes .model/model.json with the computed implements, calls, and proves links. You inspect one record with litespec model query <id>, refresh the marked regions of your pages with litespec model render, and list the gaps with litespec model check. The model page lists every finding code.
7. Share the result with litespec book --model .model/model.json --out .book. The command writes a static site with one page per record, one index per type, one lens per actor, and a review page, and the site needs no server. The book page describes each page the site holds.

Every pull request then runs the gates the CI page selects for the changed areas, such as litespec model check for a record, code, or test change and litespec consumer for a documentation change, under litespec/quality/ci#run-applicable-gates-on-every-pull-request. A gap shows up in the change that introduced it.

For example, if the shop team removed the borrow-copy handler without retiring the record, litespec model check reports use-case-unimplemented for use-case/lending.borrow-copy, and CI fails the pull request until the handler returns or an open known gap covers it.

Agent and reader paths#

You and your agent read the same release through different doors.

You read the HTML pages, starting from the standard overview and the selection page that shows which pages your shape and stacks apply. An agent starts from the selection index for your project:

https://litespec.dev/2.0.0/select/server.dotnet.react/llms.txt

That index lists the pages the server.dotnet.react selection applies, grouped by layer, with a raw Markdown link for each one. Your project AGENTS.md carries the block the index suggests, so the agent fetches only the pages a task touches:

## LiteSpec
This project follows LiteSpec 2.0.0: size small, shape server, stacks dotnet and react, extensions none.
Before a task, read https://litespec.dev/2.0.0/select/server.dotnet.react/llms.txt and fetch only the pages the task touches.
Selected extensions: none
UI work: the pattern pages listed in that index.

Every page also exists as raw Markdown at /<version>/<page>.md, such as https://litespec.dev/2.0.0/backend/domain.md, and every layer ships as one bundle at /<version>/layers/<key>.md. The schemas in schemas/ ship as JSON at /<version>/schemas/<file>, so a tool reads the same contracts the validators enforce. An agent that needs one fact queries the model instead of reading pages: litespec model query <id> prints one record with its links in both directions.

Command locations#

Some commands belong to the LiteSpec repository, most belong to a consumer, and one runs anywhere.

litespec validate and litespec provisions --check guard the standard itself: the LiteSpec workflow runs them on every change with git diff --check and a site build. litespec consumer, litespec model check, and the analyzers guard your project: your CI runs them on every pull request.

Tool questions#

Each question below names the tool that answers it and the command you run.

Next#

Read the standard explains how pages, stacks, selections, and provisions fit together, so you know which rules the tools enforce for your project. Adopt LiteSpec walks through the same change in the order a team usually does it.