Obligation
Engineering

Agents produce change faster than people can review it. A merged change proves the code compiles and its tests pass. It says nothing about the API, the documentation, the dashboard or the alert that should have shipped with it.

The usual answer is a longer instruction file. It does not work. A list of things to remember is out of date the day a new surface appears. It costs tokens on every task. And nobody can tell a forgotten MCP tool from one that was left out on purpose. Both look like silence.

So the question changes from was the code written to what does this feature owe, and is each of those things real. Those two questions have to be answered by the repository, not by a prompt and not by the agent.

1. 2.1

   Facts, not checklists.

   A feature is described by what it does, who uses it, what data it touches and how risky it is. Those facts fit on one screen.

2. 2.2

   Obligations are computed.

   A policy engine turns the facts into the exact list of things the feature owes: surfaces, access rules, data handling, tests, analytics, operations and docs.

3. 2.3

   Providers are discovered.

   Each obligation is satisfied by something real in the repository, found by reading registries and source. A comment or a claim earns nothing.

4. 2.4

   Omission is a decision.

   A missing obligation fails until a person records why it does not apply, who owns that decision and when to look again.

5. 2.5

   The commit is the proof.

   One required check runs on every commit and judges all of it. No file records that something passed.

6. 2.6

   One substrate.

   People, CI and agents run the same commands and read the same output. Instructions route to them; they do not restate them.

1. 3.1

   Describe meaning, not transports.

   A contract names a semantic operation and its facts. Routes, MCP tools, CLI verbs and screens are projections of that one identity, never the identity itself.

2. 3.2

   Stories live in code.

   Each user story is a typed identity with acceptance criteria, defined in the codebase. Everything that proves it refers to that identity, and a misspelling fails to compile.

3. 3.3

   Obligations are derived.

   A developer audience implies an API, an MCP tool and a CLI. A delete implies audit, recovery and a destructive preview. An SLO implies a metric, a dashboard, an alert and a runbook. Nobody lists these by hand.

4. 3.4

   Missing never means not applicable.

   Each obligation is met by something real, or carries a decision with a reason, an owner, a review date and an approval. The engine cannot tell the difference between forgotten and omitted, so the repository must.

5. 3.5

   Debt only goes down.

   Features that predate the policy have their gaps recorded exactly, each owned and expiring. The record can shrink. It can never grow, and its history is append-only.

6. 3.6

   The check is the proof.

   A required check passing on the commit is the evidence. No file records that a check passed, because a file can be edited. Agents change code and tests; they never regenerate receipts.

7. 3.7

   Operations are part of the contract.

   Events, logs, metrics, dashboards, alerts, runbooks, smoke tests and rollback are obligations like any other. Promotion needs a receipt from the live system, not a definition in the repository.

8. 3.8

   Every check earns its place.

   A check exists to catch a defect that nothing cheaper catches. It has an owner, a time budget, a planted failure that proves it still rejects bad input, and an expiring exception mechanism. Checks that only verified the verification system were removed.

Development starts from a specification. The prose spec explains the problem, the reasoning and the acceptance criteria. It is read by people and agents, and the context command quotes exactly the sections that matter for a task.

The stories that are enforced do not stay in prose. Each one is a typed identity in code, with its acceptance criteria beside it. Tests, rendered components, screenshots, docs pages and analytics events refer to a story by that identity. A misspelt reference fails to compile. A reference to a story the registry does not contain fails the build. Only a story written and reviewed by a person can be active; generated placeholders stay in draft and expire.

Five small artifacts make up one feature. The contract holds facts the tooling can read without running product code. The spec holds behaviour. Everything else points back at an operation or a story by identity.

The facts are a closed vocabulary. Profile says what shape the feature has: a UI flow, an API, a workflow, a library or a non-functional requirement. Effects say what an operation does to data. Audiences say who it is for. Data says whether it is stored and whether it is personal. Measurement says whether behaviour, health or a service level is tracked. Risk raises the bar. From these, and nothing else, the policy resolves what is owed.

The policy engine below is the same code that runs in CI, compiled into this page. Change the facts of one operation and the list of obligations is recomputed. Items highlighted after a change are the ones that change added.

A feature is used by people, by developers and by agents, and each of them reaches it through a different surface. The contract does not list those surfaces. It lists audiences, and the policy derives the surfaces. A customer audience owes a product UI on every shell the product has. A developer audience owes an API, a client, an MCP tool and a CLI. An automation audience owes the permissions and consent that let a machine hold a credential. An operator audience owes an admin console and its machine twins.

Each surface then declares the operation it implements, in its own registry, in its own shape. The graph joins them by identity and checks that they agree.

Obligations are due in order, and each is judged at the stage where its claim can be true. Plan, authoring and merge are deterministic and make no external writes. Promotion and runtime need evidence from the live system: a dashboard defined in the repository cannot satisfy them on its own.

A feature is not finished when its code merges. It also owes the signals that show it working for people, the signals that show it healthy, and the means to act when it is not. Each of these is an obligation with a provider, and each link between them is checked.

Fast feedback is a correctness feature. A slow check is skipped or run late, and an agent can only act on the signal it receives. So speed and cost are gates too, with the same shape as every other gate: a declared budget, a check that measures against it, and a failure that names what to fix.

Performance is also an obligation. For a critical capability the policy demands performance and reliability proof, and the provider is a test with a budget in it, not a paragraph in a plan.

The method is only as good as the loop a developer or an agent actually runs. Every step is a stable command with bounded output and a JSON form. None of them writes to a live system. The first two answer from the graph in well under a second, so the plan starts from what is owed rather than from what someone remembered.

Three loops run at different speeds. The first two block. The third may be observational by suite, but it is never allowed to stay red without an owner.

Agents work in parallel, so each works in its own worktree, and the worktree is a correctness boundary rather than a convenience. Two agents starting the same profile must never share a port, a database, an emulator or a process, and stopping one must leave the other healthy.

Every pull request is judged by one required check. It fails unless each gate below passes. Each gate is deterministic, has an owner, and names exactly what is missing and the smallest command that repairs it.

The ratchet. When the policy becomes stricter, older features are neither waved through nor blocked. Each gap is recorded by exact identity with an owner, a reason and an expiry. The record may only fall, a policy change that adds gaps must be appended as a signed entry naming them, and the whole history is compared with the merge base so it cannot be rewritten.

Documentation is an obligation like any other, and so are the images and videos inside it. They are produced by the build from the same components the product uses, so they cannot quietly fall out of date.

The repository is driven by a small set of registered commands with stable names. Each has a description, a JSON form, documented exit codes and bounded output. People and agents run the same ones, and the instruction checker rejects any instruction that names a command the registry does not contain. Select a command to run it.

Instructions are short routers, not manuals. One file at the root, one per venture and, rarely, one per package, each under a checked token budget. They say where to start, how to get context, which commands verify, and the few safety traps that cannot be inferred. They do not contain the surface checklist, because the policy owns it, and they do not restate any rule a gate already enforces.

Every harness reads the same file. The harness-specific file is one line that imports it, and the instruction check rejects any other harness-specific rule file outright. Context is retrieved per task through the context command, not repeated in every prompt.

Skills are verbs. Capabilities, packages and rules are data retrieved from the graph, so there is no skill per feature. Each skill is written once in the open skill format at the repository root, where every harness can discover it, and starts by asking the context command for its workflow and exactly one venture overlay.

The agent contract. An implementation agent is a worker inside these rules, not a judge of them.

Authority. Commands resolve to a privilege class from read-only to sensitive-destructive, strictest match wins. A sensitive command needs an explicit invocation and an approval signed outside the repository: a short-lived token bound to the exact command, revision and working directory, verified against a trust root the agent cannot write. Even then the approval authorises; it does not execute. Execution happens in a trusted clean checkout.

Most agent harnesses today are instruction-led: a carefully written instruction file, a set of skills, a few hooks, and a review. Spec-first variants add a written specification before the code. Both improve routing. Neither answers what a feature owes, and neither can tell an agent's report from a fact. Obligation Engineering keeps the routing and moves the truth into the repository.

The north star is a repository that can answer, for any change, two questions without a person remembering and without an agent being believed: what does this owe, and is each of those things real. When a repository can do that, adding an agent adds capacity and nothing else. Adding a surface, a venture or a harness changes the facts, not the method.

It is honest about its limits. A gate proves facts about the repository. Facts about the live system need receipts, and receipts expire. The policy is code that people review, and a stricter policy creates debt that must be owned rather than hidden. Nothing here replaces judgement about what is worth building. It makes sure that whatever is built arrives whole.

Every rule above started as a sentence in an instruction file. Each one was moved into a check the day it was repeated, and the sentence was deleted. That is the whole method, and it is why the instruction files stay short.