How the Tools Fit Together

The Four Tools#

LiteSpec ships two command lines, one set of .NET analyzers, and one published site. Each one serves a different reader. The pages call your project a consumer: the application repository that pins one LiteSpec release and builds against it.

The Command Line#

The litespec command line 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 consumer commands from the LiteSpec checkout with dotnet run --project apps/cli/src/LiteSpec.Cli -- <command>. In a consumer, you install the litespec command line as a local .NET tool at the adopted release, restore once with dotnet tool restore, then run dotnet litespec <command> (or dotnet tool run litespec <command>) from the consumer root. The command pages write the consumer form as litespec <command>.

The litespec-maintain command line serves the LiteSpec repository itself: validate checks the standard's pages, templates, manifest, and links, and provisions rebuilds the provision index. You run it with dotnet run --project apps/maintain/src/LiteSpec.Maintain -- <command> from the LiteSpec checkout. It is never packed for consumers. The maintainer index lists both commands with their arguments, options, and exit codes.

The CLI carries its release beside its own binary. You point it at another copy with LITESPEC_HOME, and you print its release with dotnet litespec --version.

Each command exists because the owner accepted it, and each is removed when nothing uses it. The CLI creates, checks, shows, and retrieves the specification: init, new, rename, model check, model format, model query, book, and rules.

The Analyzers#

LiteSpec.Analyzers checks .NET code while you type and while it builds. You add the package once, and each diagnostic names the provision it enforces and links to it. A provision is one rule with a stable ID, so the error points at exactly the rule the code breaks. 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 the project pinned. People read it as HTML in a browser. Agents read 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#

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. Say the team adds a use case that lets a customer cancel an order.

Adding new intent to a running project follows the one sequence under New Intent in a Running Project on the agent page. This page states no second order; it names what each tool does at the steps that sequence calls for.

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

A project starts once with dotnet litespec init --preset dotnet-react --size small at the adopted release. The command writes .litespec/project.json with shape server, stacks dotnet and react, and one frontend web at apps/web, stamped with the pinned release, with the agent context, glossary, and example cast beside it. It never overwrites an existing file. The init page lists the three presets and their selections.

New records start with dotnet litespec new, which puts a record in its one legal folder with a correct identifier. Records and the project model explains what the team writes down in Intent and Behavior.

Before editing, the agent asks which provisions govern the files it will touch: dotnet litespec rules <path> lists them grouped by strength, with the project's conventions and departures merged in. During implementation, a use case runs in one flat folder in the modules project ordered by module, aggregate, and use case, 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.

The model commands read your records and follow the marks in the backend code and the tests, the frontend routes, and the latest test run. dotnet litespec model query <id> inspects one record, dotnet litespec model check lists the gaps with a level beside each finding, dotnet litespec model format rewrites record files into canonical form, and dotnet litespec model render refreshes the marked regions of your pages. The model page lists every finding code. dotnet litespec model check --since <base> catches breaking changes against an older commit, and dotnet litespec book writes the browsable site of your project, with no server. The book page describes the shell and its views.

Every pull request then runs the gates the CI page selects for the changed areas, such as dotnet litespec model check for a record, code, or test 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 cancel-order handler without deleting the record, dotnet litespec model check reports [S use-case-unimplemented] for use-case/orders.cancel-order, and CI fails the pull request until the handler returns or a gap exception covers it.

Agent and Reader Paths#

You and your agent read the same release in different forms.

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 provisions that apply to the files it will touch:

dotnet litespec rules apps/api/src/Shop.Modules/Orders/Order/UseCases/CancelOrder/CancelOrderCommandHandler.cs

That command lists the provisions grouped by strength, as one-line statements, and --full adds rationale and example. For reading pages, the agent starts from the selection index for your project:

https://litespec.dev/4.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 4.0.0: size small, shape server, stacks dotnet and react, extensions none.
Before a task, read https://litespec.dev/4.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/4.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: dotnet litespec model query <id> prints one record with its links in both directions.

Command Locations#

Three commands belong to the LiteSpec repository, and the rest belong to a consumer.

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

Questions Each Tool Answers#

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

Next Steps#

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.