Skip to content

LiteSpec 5.2.0

Choose a tag to compare

@github-actions github-actions released this 12 Nov 17:13
· 1 commit to main since this release
5ea5d7f

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.md is 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 Commands part stays outside the region, written by the project.
  • init writes the region into a fresh AGENTS.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 render rewrites the region from the carried release and the project file: release, size, shape, stacks, layers, extensions, selection key, and command form.
  • model check reports agent-protocol-drift when the region differs from what render would write, and agent-protocol-missing when AGENTS.md holds 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 pages rules cites, then read neighboring code. The phrase "generated agent context" is gone; the query output is the task context. The rules lines cite load-applicable-provisions-before-editing.
  • The site selection page renders the same template, filled for the chosen selection, through one shared generated module. /llms.txt embeds the filled template under "Agent Protocol" instead of this repository's AGENTS.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 empty How 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 carried provisions.json, so they work offline.
  • The duty is reworded: litespec/core/agent#load-applicable-provisions-before-editing runs rules <path> before editing a file, and answers each judgment provision rules --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 when key on its **Applies to:** line: query, command, upload, document-number, erasure, project, or audit-adoption. rules returns 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 its choice and reopenedWhen, then each departure covering a provision in the result with its reason and, for a gap, its expiresOn.
  • The stage provision carries when: project, so it applies once to the project and never per record. The audit adoption provision carries when: audit-adoption, so it applies only to the decision the audit extension selection names in its new decision field 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> is https://litespec.dev/<release>/<page>/#<slug> as HTML and <page>.md as Markdown.

Decision 0038, Narrow Rules Output per File and Change Set, records why.

Part C: The LiteSpec Skill

  • templates/skill/litespec/ holds SKILL.md with references/commands.md and references/report.md. The frontmatter names litespec, 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, run rules per 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 remove deletes them. Without --agent, add installs for agents and claude, 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. add replaces a copy it wrote and refuses a folder without its marker, with exit 1; remove deletes 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-global installs it at global scope instead. Without --skill, init prints the skill add command as its last line.
  • model render rewrites project-scope copies that carry the marker. model check reports skill-drift when 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, or replacement. A product decision takes none. litespec/core/model#record-each-technical-choice-as-a-decision requires 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's 0005-render-receipts-as-pdf reads package.
  • model check reports decision-kind-missing for a technical decision with no kind, and decision-scope-invalid for a technical decision whose followers all sit in one module and each already carry an implements mark. Both are advisory.
  • The default litespec/core/agent#search-the-provisions-before-recording-a-decision queries rules for 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 follows or proves mark may name a project convention as <project>/conventions#<slug>. An unknown convention ID reports mark-unknown, as an unknown decision does. Claimwick gains one convention that a class follows.
  • A decision chooses between options at one moment, and its reopenedWhen names what would reopen it. A convention is a standing rule every change follows, and its Reviewed for question names how a reviewer finds a breach. model check reports convention-folder-invalid for a convention-shaped file under .litespec/ outside governance/conventions/, where rules never reads it. A convention's Applies to takes a path glob or the scope keys provisions use, such as stack: dotnet; artifact: command-handler, and anything neither reports convention-scope-invalid. Both are advisory. model check accepts .litespec/governance/conventions/ and the convention files in it, which the folder and page checks refused although rules reads them there.
  • Folders carry ownership and layer only. A decision's concern is computed from its followers' paths, so it cannot drift. model render writes a decision-index region into the README of each decisions folder that carries the fence, grouped by kind, then by concern, with the choice, follower count and modules, reopenedWhen, and markers for decision-unimplemented, decision-basis-missing and decision-scope-invalid. It writes a departure-index region grouped by gap or permanent, ordered by expiresOn, 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 check reports decision-home-drift for 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: a required statement holds MUST or MUST NOT, an advisory statement holds neither, and a permission on its own joins the provision it relaxes or becomes an obligation. litespec-maintain validate enforces it as STANDARD_STRENGTH_MODAL, and reports TEMPLATE_CITATION_UNKNOWN for a litespec/... citation in templates/ 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.
  • 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 carrying risk, 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/maintaining page and list the rules, model, new and skill tool 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.txt is 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 add command.
  • The guide Run Rules After Every Edit runs rules after every file edit: a Claude Code PostToolUse hook on Edit|Write that returns the short rules output as added context, a Stop hook running model check --since <base>, and an OpenCode plugin doing the same after each edit. skill add writes Markdown files only and installs no hooks.
  • Work with agents names the entry file each agent reads: Claude Code reads CLAUDE.md else the nearest AGENTS.md, and the rest read the nearest AGENTS.md except Gemini CLI with GEMINI.md. init prints a line when a CLAUDE.md does not import AGENTS.md, and model check reports agent-protocol-unreached as 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-current
  • litespec/core/agent#search-the-provisions-before-recording-a-decision
  • litespec/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

  1. Install LiteSpec.Cli 5.2.0 (dotnet tool update LiteSpec.Cli --version 5.2.0) or rerun the install script, and set reviewedLiteSpecVersion: 5.2.0 in .litespec/project.yaml.
  2. Run litespec model render. It inserts or rewrites the agent-protocol region in AGENTS.md and rewrites each project-scope skill copy. Without it, model check reports agent-protocol-missing, agent-protocol-drift, or skill-drift. render leaves text outside the region alone, so delete the ## LiteSpec section an earlier init wrote into AGENTS.md: the region replaces it.
  3. Move each provision-shaped convention to .litespec/governance/conventions/, where rules reads it. A convention-shaped file anywhere else under .litespec/ reports convention-folder-invalid.
  4. Add the decision-index fence to the README of each decisions folder to index, and the departure-index fence to the README of each departures folder, then run litespec model render to fill them.
  5. A project that selects the audit extension names its audit adoption decision in the selection's decision field. A project holding a CLAUDE.md adds the line @AGENTS.md, so Claude Code reads the protocol.
  6. A technical decision may take its kind: provider, package, format, boundary, topology, or replacement. A decision with none reports decision-kind-missing as advisory.
  7. A project that references LiteSpec.Analyzers updates it to 5.2.0.
  8. Run litespec model check and fix each finding.