Repository navigation
LiteSpec 5.2.0
LiteSpec 5.2.0 generates the agent instructions in a consumer's AGENTS.md from one template and reports when they drift, narrows rules to the provisions that apply to the edited file or the change set, ships a LiteSpec skill for Claude Code and OpenCode, and requires a technical decision only for a choice of one of six named kinds. It is a minor release: no provision ID is removed or renamed. A consumer runs model render, moves provision-shaped conventions into the conventions folder, and may give each technical decision its kind, as Part H describes.
Part A: Generated Agent Protocol in AGENTS.md
templates/consumer/project-agents.mdis the only source of the consumer protocol. Its LiteSpec part sits inside a generated region,<!-- generated:agent-protocol -->...<!-- /generated:agent-protocol -->, opening with the precedence sentence: when the file disagrees with tool output or a record, the tool output and the record win. The## Project Commandspart stays outside the region, written by the project.initwrites the region into a freshAGENTS.md, and inserts it into an existing one that holds none, after the first heading or at the end. It never touches text outside the region, and it never rewrites a region that is already there.model renderrewrites the region from the carried release and the project file: release, size, shape, stacks, layers, extensions, selection key, and command form.model checkreportsagent-protocol-driftwhen the region differs from whatrenderwould write, andagent-protocol-missingwhenAGENTS.mdholds no region. Both block.- The region holds 40 lines or fewer: commands and the rules an agent cannot guess, and no description of LiteSpec. It states one order: query the model for the records, run
rules <path>for each file to edit, read the pagesrulescites, then read neighboring code. The phrase "generated agent context" is gone; the query output is the task context. Theruleslines citeload-applicable-provisions-before-editing. - The site selection page renders the same template, filled for the chosen selection, through one shared generated module.
/llms.txtembeds the filled template under "Agent Protocol" instead of this repository'sAGENTS.md.
The rule is litespec/core/agent#keep-the-agent-protocol-current. Decision 0037, Generate the Agent Protocol, records why.
Part B: Narrower Rules Output, Change Sets and Lookup by ID
- When the target is code, provisions matched only through a marked record print as one line per record:
use-case/spending.approve-expense: <n> provisions about the record; model check checks <m>; run rules use-case/spending.approve-expense for the rest. A record path or record ID still prints them in full. rules --since <ref>takes every file changed since<ref>, returns the union with duplicates removed, leaves out the tool-checked provisions, and prints a report skeleton: one line per judgment provision with its Reviewed for question and an emptyHow judged:line.rules <provision-id>prints that provision in full: strength, statement, rationale, example, Reviewed for or Checked by, and page.rules <page-id>prints the page's provision list. Both read the carriedprovisions.json, so they work offline.- The duty is reworded:
litespec/core/agent#load-applicable-provisions-before-editingrunsrules <path>before editing a file, and answers each judgment provisionrules --since <base>lists before reporting done. The stale provision count is gone from its rationale. - A provision that holds only in some situations states a
whenkey on its**Applies to:**line:query,command,upload,document-number,erasure,project, oraudit-adoption.rulesreturns it on a code path only when the condition holds for the record the file marks; a record path prints it with its condition shown. - When the target is code, a
Decided:group prints first: each decision the file follows with itschoiceandreopenedWhen, then each departure covering a provision in the result with itsreasonand, for a gap, itsexpiresOn. - The stage provision carries
when: project, so it applies once to the project and never per record. The audit adoption provision carrieswhen: audit-adoption, so it applies only to the decision theauditextension selection names in its newdecisionfield in.litespec/project.yaml. - The site serves
/5.2.0/provisions.json, one object per provision, outside search results. The published URLs page states the ID-to-URL rule:litespec/<page>#<slug>ishttps://litespec.dev/<release>/<page>/#<slug>as HTML and<page>.mdas Markdown.
Decision 0038, Narrow Rules Output per File and Change Set, records why.
Part C: The LiteSpec Skill
templates/skill/litespec/holdsSKILL.mdwithreferences/commands.mdandreferences/report.md. The frontmatter nameslitespec, with a description that triggers on work in a repository holding.litespec/project.yaml. The body stays under 200 lines and carries the procedure, not the provisions: read the protocol region and the project file, query the model, runrulesper file, stop on unresolved conflict, check the change set, and write the completion report.litespec skill add [--agent claude|opencode|agents]... [--global]installs one generated copy per target;litespec skill removedeletes them. Without--agent,addinstalls foragentsandclaude, which together reach Claude Code and OpenCode. Each target gets its own copy, never a link, so it works in git and on Windows without Developer Mode.- Every copy carries
metadata.generated-by: litespec. A project-scope copy is also stamped with the release; a global copy names no release, so one global skill serves projects on different releases.addreplaces a copy it wrote and refuses a folder without its marker, with exit 1;removedeletes only a folder carrying the marker. Global scope writes under the user's home and needs no project file. init --skill <agent>[,<agent>]installs the skill at project scope during setup, and--skill-globalinstalls it at global scope instead. Without--skill,initprints theskill addcommand as its last line.model renderrewrites project-scope copies that carry the marker.model checkreportsskill-driftwhen a project copy differs from what the carried release generates. Global copies live outside the project and stay outside the check.
The rule is litespec/core/agent#keep-the-agent-protocol-current, which also names the skill. The skill page states the full syntax. Decision 0039, Ship a LiteSpec Skill, records why.
Part D: Decision Kinds, Convention Marks and Decision Indexes
- A technical decision carries an optional
kind:provider,package,format,boundary,topology, orreplacement. A product decision takes none.litespec/core/model#record-each-technical-choice-as-a-decisionrequires a decision only for a choice of one of the six kinds; otherwise the class documentation states the reason, and the mark names the record the class serves. Claimwick's0005-render-receipts-as-pdfreadspackage. model checkreportsdecision-kind-missingfor a technical decision with nokind, anddecision-scope-invalidfor a technical decision whose followers all sit in one module and each already carry animplementsmark. Both are advisory.- The default
litespec/core/agent#search-the-provisions-before-recording-a-decisionqueriesrulesfor the decision's subject first: where a provision makes the choice, the code follows that provision instead.litespec new decision <name>prints the provisions whose statement matches the name's words before it writes the files. - A
followsorprovesmark may name a project convention as<project>/conventions#<slug>. An unknown convention ID reportsmark-unknown, as an unknown decision does. Claimwick gains one convention that a class follows. - A decision chooses between options at one moment, and its
reopenedWhennames what would reopen it. A convention is a standing rule every change follows, and itsReviewed forquestion names how a reviewer finds a breach.model checkreportsconvention-folder-invalidfor a convention-shaped file under.litespec/outsidegovernance/conventions/, whererulesnever reads it. A convention'sApplies totakes a path glob or the scope keys provisions use, such asstack: dotnet; artifact: command-handler, and anything neither reportsconvention-scope-invalid. Both are advisory.model checkaccepts.litespec/governance/conventions/and the convention files in it, which the folder and page checks refused althoughrulesreads them there. - Folders carry ownership and layer only. A decision's concern is computed from its followers' paths, so it cannot drift.
model renderwrites adecision-indexregion into the README of each decisions folder that carries the fence, grouped bykind, then by concern, with the choice, follower count and modules,reopenedWhen, and markers fordecision-unimplemented,decision-basis-missinganddecision-scope-invalid. It writes adeparture-indexregion grouped by gap or permanent, ordered byexpiresOn, with the provisions each departure covers. - The book's decision chapter groups by kind, then by concern; each decision page lists its followers by module; and an external-system page shows the decision that chooses its provider.
model checkreportsdecision-home-driftfor a module-level decision followed from more than one module, or a product-level decision followed only from one module. It is advisory.
Decision 0040, Require Decisions Only for Six Kinds of Choice, records why.
Part E: Strength and Modal Word Agree
- The rule is
litespec/core/authoring#match-strength-to-the-modal-word: arequiredstatement holds MUST or MUST NOT, anadvisorystatement holds neither, and a permission on its own joins the provision it relaxes or becomes an obligation.litespec-maintain validateenforces it asSTANDARD_STRENGTH_MODAL, and reportsTEMPLATE_CITATION_UNKNOWNfor alitespec/...citation intemplates/that resolves to no provision. - Nine provisions are reworded, each keeping its ID:
- Required, now obliging:
core/agent#follow-the-local-pattern-before-the-model-query,core/agent#replace-only-declared-conventions,core/authoring#keep-a-pinned-release-for-as-long-as-it-serves,core/use-cases#exercise-rules-from-scenarios,core/use-cases#share-scenario-setup-in-background,frontend/components#place-a-drawing-no-composite-makes-in-an-exception-file. - Advisory, now suggesting with a Deviation:
frontend/testing#test-observable-states,workspace/naming#use-current-language-features,workspace/naming#use-intent-revealing-boolean-names.
- Required, now obliging:
- For
follow-the-local-pattern-before-the-model-query, the statement reads "An agent MUST run the model query before a change that touches a permission carryingrisk, and MAY rely on neighboring code otherwise." Its heading, and its rename, wait for 6.0.
Part F: The Documentation and litespec.dev
- Selection indexes describe each page with its Intent's first sentence, with links rewritten the way page bodies are. They leave out the maintainer-only
core/maintainingpage and list therules,model,newandskilltool pages with the Published URLs page. A "By Artifact" section names, for each artifact kind, the pages of the selection that carry provisions for it. Each index stays under 25 KB. /<version>/llms-full.txtis removed: Cloudflare analytics recorded no request for it in the 29 days before this release, while the indexes kept their readers. The layer bundles stay, and each section heading of a selection index links the bundle that carries the same text.- The "Use with Agents" page shows the full generated block and a third step, "Install the Skill", with the
skill addcommand. - The guide Run Rules After Every Edit runs
rulesafter every file edit: a Claude CodePostToolUsehook onEdit|Writethat returns the shortrulesoutput as added context, aStophook runningmodel check --since <base>, and an OpenCode plugin doing the same after each edit.skill addwrites Markdown files only and installs no hooks. - Work with agents names the entry file each agent reads: Claude Code reads
CLAUDE.mdelse the nearestAGENTS.md, and the rest read the nearestAGENTS.mdexcept Gemini CLI withGEMINI.md.initprints a line when aCLAUDE.mddoes not importAGENTS.md, andmodel checkreportsagent-protocol-unreachedas advisory for the same gap.
Part G: Provision Changes Since v5.1.0
Provision Changes Since v5.1.0
Added (3):
litespec/core/agent#keep-the-agent-protocol-currentlitespec/core/agent#search-the-provisions-before-recording-a-decisionlitespec/core/authoring#match-strength-to-the-modal-word
Removed (0):
None.
Renamed (0):
None.
Extensions added (0):
None.
Extensions removed (0):
None.
Part H: Upgrading a Consumer
- Install
LiteSpec.Cli5.2.0 (dotnet tool update LiteSpec.Cli --version 5.2.0) or rerun the install script, and setreviewedLiteSpecVersion: 5.2.0in.litespec/project.yaml. - Run
litespec model render. It inserts or rewrites theagent-protocolregion inAGENTS.mdand rewrites each project-scope skill copy. Without it,model checkreportsagent-protocol-missing,agent-protocol-drift, orskill-drift.renderleaves text outside the region alone, so delete the## LiteSpecsection an earlierinitwrote intoAGENTS.md: the region replaces it. - Move each provision-shaped convention to
.litespec/governance/conventions/, whererulesreads it. A convention-shaped file anywhere else under.litespec/reportsconvention-folder-invalid. - Add the
decision-indexfence to the README of each decisions folder to index, and thedeparture-indexfence to the README of each departures folder, then runlitespec model renderto fill them. - A project that selects the
auditextension names its audit adoption decision in the selection'sdecisionfield. A project holding aCLAUDE.mdadds the line@AGENTS.md, so Claude Code reads the protocol. - A technical decision may take its
kind:provider,package,format,boundary,topology, orreplacement. A decision with none reportsdecision-kind-missingas advisory. - A project that references
LiteSpec.Analyzersupdates it to 5.2.0. - Run
litespec model checkand fix each finding.