Type to search pages and rules.

Browse pages

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.

Markdown

Intent#

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.

What an agent gets from LiteSpec#

Without LiteSpec, an agent decides architecture, naming, and testing from its training and from whatever files it happens to open. With LiteSpec, those choices are already made and written down, so the agent spends its effort on the work you asked for.

An agent gets three things:

  • Rules it can cite. Every rule has an ID, so the agent can say exactly which rule a change follows or why it stopped.
  • Records it can trust. Approved records say what to build. Draft records say what's still open.
  • Checks it can run. litespec consumer, litespec model check, and your CI gates tell the agent whether its change holds before you review it.

How an agent finds the rules#

There are two ways, and you can use both.

From the pinned release. When your project pins LiteSpec as a submodule at litespec/, the rules sit in the repository next to your code. Your project's AGENTS.md tells the agent to read them, and the agent reads only the pages a task touches.

From the site. An agent that can fetch URLs can read the standard from litespec.dev without a local copy. The selection page gives you a block to paste into your AGENTS.md:

Markdown
## 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.

That index lists every page your selection applies, with a one-line description and a raw Markdown link for each. An agent reads the index, then fetches the few pages a task needs. Every page of the site also exists as plain Markdown: add .md to the page's path.

How an agent works on a task#

The agent page states the order, and the project's AGENTS.md repeats it:

  1. Read the project's AGENTS.md and litespec.project.json.
  2. Query the model for the records the task touches, with litespec model query <id>.
  3. Read those records, then the full standards pages they cite.
  4. Look at neighboring code and follow a pattern that complies.
  5. Change the records, code, tests, and contracts that belong together, in one change.
  6. Run the checks, and report each command, its result, and anything skipped.

The diagram below shows that order, and where the agent stops for a person instead of deciding alone.

The order an agent loads context, and where it stops The agent reads eight steps in order: the project agents file and project file, the selection index, the records the task touches, the full standards pages, the selected extensions, the neighboring code, then the change itself, and finally the checks and the report. When blocked by a conflict, a draft, or a product call, it stops for a person instead, which can happen at any step. 1. Project agents file and project file 2. Selection index 3. Records the task touches 4. Full standards pages 5. Selected extensions 6. Neighboring code 7. Change records, code, tests 8. Run the checks and report Stop for a person AGENTS.md and litespec.project.json only the pages the task touches litespec model query <id> the pages the records cite only inside their boundary follow a complying pattern what belongs together, in one change each command and its result conflict, draft, product call blocked The agent can stop at any step. An arrow is the next step; the branch says when the agent stops for a person instead.
The agent reads the project files, the selection index, the records, the standards pages, extensions, and neighboring code, then changes, checks, and reports, and stops for a person when blocked.

For example, an agent asked to change how borrowing works starts with one query:

Shell
litespec model query use-case/lending.borrow-copy

The answer prints the record with its links in both directions, so the agent reads the requirement, the rule, and the results the use case touches, then the standards pages they cite, before it opens the handler. The LiteSpec block in the project's AGENTS.md, shown above, tells the agent where the selection index lives.

When two rules conflict and nothing decides between them, the agent stops and asks, quoting both rule IDs.

What an agent decides, and what it leaves to you#

An agent makes the decisions the standard has already made for it: where a type goes, how a lifecycle is modeled, how a refusal is reported, and which tests to write. It doesn't decide product policy, legal questions, money, or risk. When a record leaves one of those open, the agent names the question and its decider instead of answering it.

UI design works the same way. For each recurring interface question, LiteSpec offers drawn options and a default. An agent shows you the options with litespec patterns preview, recommends one, and builds the one you choose in your own components and style. If it sees a better option while working, it finishes on your choice and proposes the idea in its report, instead of changing your decision.

Next#

Adopt LiteSpec walks through what changes for a team that starts using it.