# Agent Operating Protocol **Stack:** any **Layer:** workspace ## Intent 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. ## 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](https://litespec.dev/4.0.0/core/model.md) states the record types and their links. An agent queries that model for the records a task touches: `litespec model query ` 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](https://litespec.dev/4.0.0/core/scope.md) 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](https://litespec.dev/4.0.0/core/intent.md) 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 ` 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. 1. Scaffold Intent. Load the records the change touches with `dotnet litespec model query `, 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. 2. Specify Behavior. Scaffold the use case, its results, and its scenarios with `dotnet litespec new `, `dotnet litespec new result `, and `dotnet litespec new scenario `, naming the rules, access, aggregates, consistency, and effects the use case carries. 3. Validate the records. Run `dotnet litespec model check` and fix every finding before code moves. 4. Load provisions and choose patterns. Run `dotnet litespec rules ` for each path the change touches before editing it. Build the pattern Default and record it with `source: recommended`, and wait for an owner only when the route departs from the Default or no Default exists. Scaffold each screen with `dotnet litespec new screen .`. 5. Implement. Build the Domain change, the handler, the endpoint, the persistence, and the frontend, in that layer order, with `dotnet build` for 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. 6. 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. 7. Run the gates and the model commands in order. Run the boundary-selected gates and the test suites first, then `dotnet litespec model check`, then `dotnet litespec model render`. 8. Check the change against its base and merge complete. Run `dotnet litespec model check --since ` for the owner review, where `` in a consumer is the consumer default branch, such as `main`, 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 with `expiresOn`. 9. 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 `expiresOn` for each check held red. ## Standards ### Select Task Context **ID:** `litespec/core/agent#select-task-context` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST query the project model for the records that cover the request, and read the generated agent context, before editing. **Rationale:** 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. **Reviewed for:** The completion report names the model query that selected the cited records. ### Follow the Local Pattern Before the Model Query **ID:** `litespec/core/agent#follow-the-local-pattern-before-the-model-query` **Strength:** rule **Applies to:** artifact: any **Statement:** A change touching no permission that carries `risk` MAY skip the model query, reading the agent context and neighboring code instead. **Rationale:** 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. **Reviewed for:** The change touches no permission carrying `risk` and names the local pattern it followed. ### Load Applicable Extensions **ID:** `litespec/core/agent#load-applicable-extensions` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST load selected project extensions and selected applicable local extensions before editing code or prose inside the extension's boundary. **Rationale:** 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. **Reviewed for:** The change names each extension loaded before editing inside its boundary. ### Load Applicable Provisions Before Editing **ID:** `litespec/core/agent#load-applicable-provisions-before-editing` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST run `litespec rules ` before editing a file and answer each returned provision's Reviewed for question before reporting done. **Rationale:** 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. **Reviewed for:** Which provisions the rules query returned lack a judged answer in the completion report? Compare the rules output with the report. ### Apply Guidance Precedence **ID:** `litespec/core/agent#apply-guidance-precedence` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST apply the project exception, the extension, the deeper page, and the shallower page in that order. **Rationale:** 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. **Reviewed for:** The design applies the project exception, the extension, the deeper page, and the shallower page in that order. ### Replace Only Declared Conventions **ID:** `litespec/core/agent#replace-only-declared-conventions` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MAY apply a replacement for a convention only when the project documentation records that replacement. **Rationale:** 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. **Reviewed for:** Each convention replacement resolves to a recorded local convention in the project documentation. ### Stop on Unresolved Conflict **ID:** `litespec/core/agent#stop-on-unresolved-conflict` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST stop when applicable provisions disagree without declared precedence and quote both provision IDs and paths. **Rationale:** 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. **Reviewed for:** The stopped work quotes the conflict with both provision IDs and paths. ### Inspect Existing Work Before Editing **ID:** `litespec/core/agent#inspect-existing-work-before-editing` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST read `git status` before editing and preserve user changes, untracked files, and unrelated generated output. **Rationale:** 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. **Reviewed for:** `git status` output precedes the edits, with user changes, untracked files, and unrelated generated output untouched. ### Restrict Unapproved Side Effects **ID:** `litespec/core/agent#restrict-unapproved-side-effects` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST NOT act without approval on packages, migrations, authentication, a public API, production data, releases, spending, or outside calls that change state. **Rationale:** 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. **Reviewed for:** An approval covers each package, migration, authentication, public API, production data, release, spending, or state-changing outside call the change makes. ### Make Coherent Scoped Changes **ID:** `litespec/core/agent#make-coherent-scoped-changes` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST make the smallest coherent change that satisfies the authorized request. **Rationale:** 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. **Reviewed for:** Every changed artifact traces to the authorized request. ### Take Expected Values from the Scenario **ID:** `litespec/core/agent#take-expected-values-from-the-scenario` **Strength:** rule **Applies to:** artifact: test **Statement:** An agent MUST take a test's expected values only from the scenario's Then, never from running the code. **Rationale:** 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. **Reviewed for:** Each test's expected values match the scenario's Then, with none taken from a code run. ### Verify Refusals and Calculations Against Held-Back Examples **ID:** `litespec/core/agent#verify-refusals-and-calculations-against-held-back-examples` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST verify a refusal or calculation implementation against example rows held back from the agent that wrote it. **Rationale:** 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. **Reviewed for:** The check log shows refusal and calculation example rows withheld during implementation and run after. ### Write Pages Below Decided Intent **ID:** `litespec/core/agent#write-pages-below-decided-intent` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST write every page below decided Intent. **Rationale:** 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. **Reviewed for:** Each written page traces to a decided Intent record, with no invented promise. ### Escalate Decisions That Specify Forbids **ID:** `litespec/core/agent#escalate-decisions-that-specify-forbids` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST NOT decide a figure the owner sets. **Rationale:** 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](https://litespec.dev/4.0.0/core/intent.md) 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. **Reviewed for:** Each figure the owner sets that the change needs sits in an owner question or a backlog item, not in an agent-written decision. ### Raise Open Figures to the Owner **ID:** `litespec/core/agent#raise-open-figures-to-the-owner` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST raise each open figure to the owner with a recommendation, or place it on the backlog board. **Rationale:** 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. **Reviewed for:** Which 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. ### Name Judged Provisions in the Completion Report **ID:** `litespec/core/agent#name-judged-provisions-in-the-completion-report` **Strength:** rule **Applies to:** artifact: any **Statement:** A completion report MUST name each provision the agent judged and how it judged it. **Rationale:** 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. **Reviewed for:** Which judged provisions lack a how in the completion report? Look at the provisions beside the report. ### Advise Without Gating **ID:** `litespec/core/agent#advise-without-gating` **Strength:** rule **Applies to:** artifact: any **Statement:** An agent MUST report its findings as advice with evidence, never as a decision. **Rationale:** 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. **Reviewed for:** The agent output records findings as advice with evidence, with decisions left to the owner. ## Conventions ### Read the Full Record Before Changing a Boundary **ID:** `litespec/core/agent#read-the-full-record-before-changing-a-boundary` **Strength:** default **Applies to:** artifact: any **Default:** Read the full record, the record file with its explanation file, before generating a file, changing a public boundary, or choosing between patterns. **Replacement:** A consumer records a boundary-reading convention naming which changes need the full record. **Rationale:** 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. **Reviewed for:** Each file generation or boundary change cites the full record it matched. ### Inspect Local Examples After Standards **ID:** `litespec/core/agent#inspect-local-examples-after-standards` **Strength:** default **Applies to:** artifact: any **Default:** Inspect neighboring consumer files after loading applicable standards. **Replacement:** A consumer records an inspection convention naming which neighboring files an agent reads. **Rationale:** 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. **Reviewed for:** The change names the neighboring files that shaped it after the standards. ### Keep Agent Working Files Under Agents **ID:** `litespec/core/agent#keep-agent-working-files-under-agents` **Strength:** default **Applies to:** artifact: any **Default:** Keep agent working files under `.agents/`, with tracked `skills/` and `records/` folders and ignored `scratch/` and `delegate/` folders. **Replacement:** A consumer records a working-files convention naming where agents keep working files. **Rationale:** 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:** ```text .agents/ skills/ records/ delegate/ scratch/ ``` **Reviewed for:** Every agent working file sits under `.agents/` or the path the working-files convention names. ## 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.