Browse pages
Agent Operating Protocol
An agent is software that reads task context, edits files, and runs checks. This page states the operating rules for an agent working in a LiteSpec project: which records of decided intent to read before editing, which provisions govern each change, which guidance wins when pages overlap, and which changes need the task authorizer before the agent acts. Following them keeps each run inside its authorized scope, preserves unrelated work, and ends it with a report the owner can check.
Stack: any Layer: workspace
Concepts#
The Project Model and the Agent Context#
A consumer project describes itself with records of fixed types in four record layers: Intent states the promises, Behavior states how the system keeps them, Implementation holds code and technical decisions, and Proof shows the checks. Governance is a group of records beside the four record layers, not a fifth layer. The model page states the record types and their links. An agent queries that model for the records a task touches: litespec model query <id> prints one record with its links in both directions, such as a use case with its rules, results, and scenarios.
The generated agent context is the rendered summary of that selection: the smallest record set that covers the request, with the links the builder joined between records. Code, screens, and tests point up to the records they serve. Reading the context before editing starts the run from decided Intent instead of repository guesswork.
Extensions and Their Boundaries#
An extension is a conditional standards bundle a project selects when its criterion holds. A selected project extension applies to the whole project, while a selected local extension applies only inside its own boundary, such as one frontend or one module. The scope page states how a project selects extensions. Editing inside an extension's boundary without loading the extension follows baseline guidance the extension replaced.
Guidance Precedence#
Guidance overlaps by design: a project exception narrows a shared provision, an extension replaces a baseline default, and a stack page refines its area page. The precedence order decides which one wins: the project exception first, then the extension, then the deeper page, then the shallower page. A deeper page is one that sits further down the documentation tree, such as a stack page under its area page. The most local decision wins, and the broader baseline fills only the gaps it leaves.
Agents Write Below Decided Intent#
The specification is closed: the owner decides Intent, and agents write the records below those decisions, through Behavior down to code and tests. The Specify rule forbids agents from deciding the figures the owner sets on their own; the Intent page states the Specify boundary. Something that seems missing becomes a question to the owner or a backlog item, never code.
Side Effects That Need the Task Authorizer#
Some changes reach beyond an ordinary implementation edit: they alter project boundaries, move money or data, or change state outside the repository. Each such change needs the task authorizer's approval before the agent acts, because the task text alone never justifies it. The side-effect provision below lists the changes it covers.
Ask the Tool Which Provisions Apply#
litespec rules <path or record id> lists the provisions that apply to a change, grouped by strength, as one-line statements, with project conventions and departures merged in. litespec rules <...> --full adds rationale and example when a statement is not enough. An agent runs the query before editing and answers each returned provision's Reviewed for question before reporting done, and the completion report names the provisions the agent judged and how.
Git Is the Decision Record#
A record in the repository is decided, and the pull request that changes it is its review. A record nobody wants is deleted; git keeps its history. An agent reads who changed what and when from git, never from record fields.
Work in Progress#
A branch may be incomplete; what merges is complete. litespec model check reports reachability locally and blocks on it in the pull-request check. A record that must stay unreached past a merge carries an exception with expiresOn, which parks reachability for that record until it expires.
New Intent in a Running Project#
A running project takes new intent through this one sequence. Other pages link to this sequence instead of stating their own order.
- Scaffold Intent. Load the records the change touches with
dotnet litespec model query <id>, add or confirm the problem and the feature, then the requirement and the journey step, and raise every undecided figure, such as a price, a term, a retention period, or a date-dependent default, to the owner with a recommendation or place it on the backlog board. - Specify Behavior. Scaffold the use case, its results, and its scenarios with
dotnet litespec new <type> <id>,dotnet litespec new result <use-case-id> <name>, anddotnet litespec new scenario <use-case-id> <name>, naming the rules, access, aggregates, consistency, and effects the use case carries. - Validate the records. Run
dotnet litespec model checkand fix every finding before code moves. - Load provisions and choose patterns. Run
dotnet litespec rules <path>for each path the change touches before editing it. Build the pattern Default and record it withsource: recommended, and wait for an owner only when the route departs from the Default or no Default exists. Scaffold each screen withdotnet litespec new screen <entry-point>.<name>. - Implement. Build the Domain change, the handler, the endpoint, the persistence, and the frontend, in that layer order, with
dotnet buildfor the backend code. Authorizer gate: the task authorizer approves before this step adds a package, a schema migration, an authentication change, a public API change, production data work, a release, spending, or an outside call that changes state. - Write proofs from Then. Write one test for each scenario through the public boundary, taking every expected value only from the scenario Then. Refusals and calculations also run against the example rows held back from the agent that wrote the code, and the suites in the next step run the proofs.
- Run the gates and the model commands in order. Run the boundary-selected gates and the test suites first, then
dotnet litespec model check, thendotnet litespec model render. - Check the change against its base and merge complete. Run
dotnet litespec model check --since <base>for the owner review, where<base>in a consumer is the consumer default branch, such asmain, unless it names a consumer folder or another git revision the review names; the run reports every breaking contract change since the base. A branch may be incomplete; what merges is complete: the pull-request check blocks on unreached records, and a record that must stay unreached past a merge carries an exception withexpiresOn. - Write the release record. Create the release record for the immutable artifact and pass the release gate: green checks, every scenario proven by a passing test, and an exception with
expiresOnfor each check held red.
Standards#
Select Task Context#
ruleruleguidancelitespec/core/agent#select-task-contextAn agent MUST query the project model for the records that cover the request, and read the generated agent context, before editing.
Applies toartifact: any
Why
Without the query, an agent reads either too little and invents the missing rules, or half the repository and buries the task in unrelated guidance. The query returns the smallest record set that covers the request, with the links the builder joined between records, so the agent starts from decided Intent.
Example
litespec model query use-case/spending.submit-expense returns the use case with its rules, results, and scenarios.
Checka reviewer answers
Reviewed forThe completion report names the model query that selected the cited records.
Marked guidance: a reviewer answers this question.
Follow the Local Pattern Before the Model Query#
ruleruleguidancelitespec/core/agent#follow-the-local-pattern-before-the-model-queryA change touching no permission that carries risk MAY skip the model query, reading the agent context and neighboring code instead.
Applies toartifact: any
Why
A small edit with no risk behind it does not need the full record set: the agent context plus the neighboring file already show the decided shape. Requiring a model query for every small change would slow ordinary work without adding information. A change touching a permission that carries risk keeps the full query, because the query shows the risk a one-line change would otherwise miss, and it costs seconds.
Example
A spelling fix in a setting page reads the agent context and the sibling setting, then edits without querying the model.
Checka reviewer answers
Reviewed forThe change touches no permission carrying risk and names the local pattern it followed.
Marked guidance: a reviewer answers this question.
Load Applicable Extensions#
ruleruleguidancelitespec/core/agent#load-applicable-extensionsAn agent MUST load selected project extensions and selected applicable local extensions before editing code or prose inside the extension's boundary.
Applies toartifact: any
Why
An extension replaces baseline guidance inside its boundary. An agent that edits there without loading the extension follows the baseline the extension replaced, and the change contradicts the project's own selection.
Example
A change to the cached catalog reads the selected caching extension before touching the code its boundary covers.
Checka reviewer answers
Reviewed forThe change names each extension loaded before editing inside its boundary.
Marked guidance: a reviewer answers this question.
Load Applicable Provisions Before Editing#
ruleruleguidancelitespec/core/agent#load-applicable-provisions-before-editingAn agent MUST run litespec rules <path> before editing a file and answer each returned provision's Reviewed for question before reporting done.
Applies toartifact: any
Why
1,800 provisions are only usable when retrieved by situation: the query returns what governs the change, grouped by strength, with project conventions and departures merged in. litespec rules <...> --full adds rationale and example when a statement is not enough.
Example
litespec rules use-case/spending.submit-expense returns the provisions that govern the change, grouped by strength.
Checka reviewer answers
Reviewed forWhich provisions the rules query returned lack a judged answer in the completion report? Compare the rules output with the report.
Marked guidance: a reviewer answers this question.
Apply Guidance Precedence#
ruleruleguidancelitespec/core/agent#apply-guidance-precedenceAn agent MUST apply the project exception, the extension, the deeper page, and the shallower page in that order.
Applies toartifact: any
Why
Overlapping guidance is normal: a project exception narrows a shared provision, an extension replaces a baseline default, and a stack page refines its area page. Without a fixed order, two agents resolve the same overlap differently and the workspace drifts. The order puts the most local decision first, so the broader baseline fills only the gaps it leaves.
Checka reviewer answers
Reviewed forThe design applies the project exception, the extension, the deeper page, and the shallower page in that order.
Marked guidance: a reviewer answers this question.
Replace Only Declared Conventions#
ruleruleguidancelitespec/core/agent#replace-only-declared-conventionsAn agent MAY apply a replacement for a convention only when the project documentation records that replacement.
Applies toartifact: any
Why
Conventions exist to be replaced, but only through a recorded decision. An undocumented local preference that silently replaces a baseline default looks identical to a mistake, so the next agent fixes it back. The recorded convention keeps the replacement visible and reviewable.
Checka reviewer answers
Reviewed forEach convention replacement resolves to a recorded local convention in the project documentation.
Marked guidance: a reviewer answers this question.
Stop on Unresolved Conflict#
ruleruleguidancelitespec/core/agent#stop-on-unresolved-conflictAn agent MUST stop when applicable provisions disagree without declared precedence and quote both provision IDs and paths.
Applies toartifact: any
Why
When two provisions disagree and no precedence decides, any continuation invents a compromise neither provision states. Stopping with both provision identifiers and paths hands the decision to a person with exactly the evidence the decision needs.
Checka reviewer answers
Reviewed forThe stopped work quotes the conflict with both provision IDs and paths.
Marked guidance: a reviewer answers this question.
Inspect Existing Work Before Editing#
ruleruleguidancelitespec/core/agent#inspect-existing-work-before-editingAn agent MUST read git status before editing and preserve user changes, untracked files, and unrelated generated output.
Applies toartifact: any
Why
A working tree can hold the user's own uncommitted edits, untracked files, and generated output from an unrelated task. An agent that edits without looking overwrites or deletes work outside its scope. Reading git status first marks that work as untouchable.
Checka reviewer answers
Reviewed forgit status output precedes the edits, with user changes, untracked files, and unrelated generated output untouched.
Marked guidance: a reviewer answers this question.
Restrict Unapproved Side Effects#
ruleruleguidancelitespec/core/agent#restrict-unapproved-side-effectsAn agent MUST NOT act without approval on packages, migrations, authentication, a public API, production data, releases, spending, or outside calls that change state.
Applies toartifact: any
Why
The listed changes alter project boundaries beyond an ordinary implementation edit: they move money or data, open security boundaries, or change state outside the repository. None of them can be judged from the task text alone, so the task authorizer approves each one before the agent acts.
Checka reviewer answers
Reviewed forAn approval covers each package, migration, authentication, public API, production data, release, spending, or state-changing outside call the change makes.
Marked guidance: a reviewer answers this question.
Make Coherent Scoped Changes#
ruleruleguidancelitespec/core/agent#make-coherent-scoped-changesAn agent MUST make the smallest coherent change that satisfies the authorized request.
Applies toartifact: any
Why
A change that stops at code and skips its records, tests, or operating evidence leaves the workspace claiming behavior nothing proves. A change that sprawls past the request drags unrelated files into review. The smallest coherent change keeps the records, code, tests, and evidence that belong together in one reviewable unit.
Checka reviewer answers
Reviewed forEvery changed artifact traces to the authorized request.
Marked guidance: a reviewer answers this question.
Take Expected Values from the Scenario#
ruleruleguidancelitespec/core/agent#take-expected-values-from-the-scenarioAn agent MUST take a test's expected values only from the scenario's Then, never from running the code.
Applies toartifact: test
Why
Expected values read from a passing run restate what the code already does, so the test stays green while behavior drifts. The scenario's Then states the decided intent, which makes the test check the behavior rather than copy it.
Example
A scenario whose Then names a total of 42.50 keeps 42.50 as the asserted value even when the code returns 42.51: the mismatch fails the test instead of updating the expectation.
Checka reviewer answers
Reviewed forEach test's expected values match the scenario's Then, with none taken from a code run.
Marked guidance: a reviewer answers this question.
Verify Refusals and Calculations Against Held-Back Examples#
ruleruleguidancelitespec/core/agent#verify-refusals-and-calculations-against-held-back-examplesAn agent MUST verify a refusal or calculation implementation against example rows held back from the agent that wrote it.
Applies toartifact: any
Why
An agent that sees the examples while implementing fits the code to the rows instead of the rule. Held-back rows turn the examples into an independent check: the implementing agent works from the rule and the scenario, and a later check runs the withheld rows against the result.
Example
The implementing agent writes a discount calculation from its rule and scenario; a later check runs the withheld example rows against the result.
Checka reviewer answers
Reviewed forThe check log shows refusal and calculation example rows withheld during implementation and run after.
Marked guidance: a reviewer answers this question.
Write Pages Below Decided Intent#
ruleruleguidancelitespec/core/agent#write-pages-below-decided-intentAn agent MUST write every page below decided Intent.
Applies toartifact: any
Why
Intent holds the decided promises, and everything below those decisions is written by agents: Behavior records, code, and tests that carry the decisions down. An agent that invents promises writes commitments nobody decided, while an agent that waits for dictation wastes the reading the owner gives to finished work. Writing below decided Intent keeps authorship with the agent and decisions with the owner.
Example
Given a requirement for expense reimbursement, an agent writes the use case, its scenarios, and the handler without asking what the promise means.
Checka reviewer answers
Reviewed forEach written page traces to a decided Intent record, with no invented promise.
Marked guidance: a reviewer answers this question.
Escalate Decisions That Specify Forbids#
ruleruleguidancelitespec/core/agent#escalate-decisions-that-specify-forbidsAn agent MUST NOT decide a figure the owner sets.
Applies toartifact: any
Why
The Specify rule reserves the figures the owner sets for Intent, because each one binds the product to buyers, markets, or law; the Intent page states the Specify boundary. An agent that picks a figure silently takes a decision that belongs to the owner. Each undecided figure becomes a question to the owner with a recommendation, or a backlog item.
Example
A setting needs a default queue cap; the agent raises a question to the owner with a recommendation instead of writing the default into the record.
Checka reviewer answers
Reviewed forEach figure the owner sets that the change needs sits in an owner question or a backlog item, not in an agent-written decision.
Marked guidance: a reviewer answers this question.
Raise Open Figures to the Owner#
ruleruleguidancelitespec/core/agent#raise-open-figures-to-the-ownerAn agent MUST raise each open figure to the owner with a recommendation, or place it on the backlog board.
Applies toartifact: any
Why
A figure without a recommendation asks the owner to research from nothing, while a recommendation gives a default to accept or correct. Grouping figures by subject lets the owner answer one set at a time. A figure never becomes a silent agent decision or code written on a guess.
Example
Two open figures land in one owner question set, each with a recommendation.
Checka reviewer answers
Reviewed forWhich open figures lack an owner question with a recommendation or a backlog item? Look at the owner questions and the backlog board beside the change.
Marked guidance: a reviewer answers this question.
Name Judged Provisions in the Completion Report#
ruleruleguidancelitespec/core/agent#name-judged-provisions-in-the-completion-reportA completion report MUST name each provision the agent judged and how it judged it.
Applies toartifact: any
Why
The report shows which rules, defaults, and advice the change met and the judgment for each, so the owner checks the reasoning without re-reading the change. A provision the query returned but the report skips is a judgment nobody can check.
Example
The report names each returned provision with its judgment: followed, replaced by a named convention, or parked by an exception.
Checka reviewer answers
Reviewed forWhich judged provisions lack a how in the completion report? Look at the provisions beside the report.
Marked guidance: a reviewer answers this question.
Advise Without Gating#
ruleruleguidancelitespec/core/agent#advise-without-gatingAn agent MUST report its findings as advice with evidence, never as a decision.
Applies toartifact: any
Why
Decisions belong to the owner: the pull request that changes a record is its review. An agent that records a decision spends authority it was never given. Advice with evidence lets the owner decide faster without moving the decision to the agent.
Checka reviewer answers
Reviewed forThe agent output records findings as advice with evidence, with decisions left to the owner.
Marked guidance: a reviewer answers this question.
Conventions#
Read the Full Record Before Changing a Boundary#
conventiondefaultguidancelitespec/core/agent#read-the-full-record-before-changing-a-boundaryRead the full record, the record file with its explanation file, before generating a file, changing a public boundary, or choosing between patterns.
ReplacementA consumer records a boundary-reading convention naming which changes need the full record.
Applies toartifact: any
Why
Generating a file or changing a public boundary from a summary risks baking a paraphrase into a contract. The full record carries the exact fields, links, and wording the new surface matches. A small edit that follows an existing local pattern can rely on the generated agent context instead.
Checka reviewer answers
Reviewed forEach file generation or boundary change cites the full record it matched.
Marked guidance: a reviewer answers this question.
Inspect Local Examples After Standards#
conventiondefaultguidancelitespec/core/agent#inspect-local-examples-after-standardsInspect neighboring consumer files after loading applicable standards.
ReplacementA consumer records an inspection convention naming which neighboring files an agent reads.
Applies toartifact: any
Why
Standards state the required shape, while neighboring files show the names, folders, and idioms this project chose for it. An agent that skips them writes compliant but foreign-looking code that the next edit rewrites.
Checka reviewer answers
Reviewed forThe change names the neighboring files that shaped it after the standards.
Marked guidance: a reviewer answers this question.
Keep Agent Working Files Under Agents#
conventiondefaultguidancelitespec/core/agent#keep-agent-working-files-under-agentsKeep agent working files under .agents/, with tracked skills/ and records/ folders and ignored scratch/ and delegate/ folders.
ReplacementA consumer records a working-files convention naming where agents keep working files.
Applies toartifact: any
Why
Agent work with no agreed home lands beside authored records, where it pollutes review, or vanishes with the session, where nobody can audit it. The split keeps durable work in skills/ and records/ and machine-local work in the ignored scratch/ and delegate/ folders.
Example
.agents/
skills/
records/
delegate/
scratch/Checka reviewer answers
Reviewed forEvery agent working file sits under .agents/ or the path the working-files convention names.
Marked guidance: a reviewer answers this question.
Reference Example#
This informative example demonstrates litespec/core/agent#select-task-context, litespec/core/agent#load-applicable-provisions-before-editing, litespec/core/agent#load-applicable-extensions, litespec/core/agent#raise-open-figures-to-the-owner, and litespec/core/agent#inspect-local-examples-after-standards.
A command-handler change for use-case/spending.submit-expense queries the model for its use case, reads the generated agent context, runs litespec rules for the handler path, and loads the selected extensions whose boundary the change touches. It then reads the neighboring handler for local names and shapes. Open figures go to the owner with recommendations, and the completion report names each judged provision with its judgment. It leaves unrelated frontend and container guidance unread.