Why Coding Agents Need Repo Contracts, Not Bigger Context Windows

Most coding-agent failures do not happen because the model forgot how to write code.

They happen because the repo never said what "correct" means.

A bigger context window can help an agent read more files, more docs, more CI logs, and more scripts. But if the repository's real operating assumptions are scattered across README notes, shell history, CI YAML, .env.example, local services, and tribal knowledge, more context only gives the agent a larger pile of ambiguity.

The missing piece is not memory. It is a repo contract.

A repo contract tells humans and agents how the project is meant to be prepared, verified, and run. It makes setup requirements, services, environment assumptions, safe tasks, workflows, and runtime proof explicit.

That matters because coding agents do not just need source code. They need operational truth.

A large context window can show an agent many signals at once:

• the README says npm test
• CI runs pnpm install --frozen-lockfile before a longer verification workflow
• a shell script starts Redis before tests
• .env.example contains values the README never mentions
• the package manifest has several plausible dev commands
• a contributor guide says Docker is optional, but some tasks fail without it

That is more information, but it is not governance.

The agent still has to decide which signal is authoritative. It has to infer whether README prose is current, whether CI applies locally, whether the shell script is safe to run, whether the env file is required or illustrative, and whether a failed command means a code defect or a missing repo assumption.

When the repo does not declare the answer, the agent guesses.

Sometimes it guesses well. Sometimes it burns time. Sometimes it edits around a setup problem. Sometimes it passes the wrong check and leaves the real failure untouched.

The problem is not that the agent needed an even larger window.

The problem is that the repo never gave it a stable operating contract.

A useful coding agent needs to know more than where the files are.

It needs to know:

• which command is canonical
• which setup steps are required
• which services must be running
• which environment variables are real requirements
• which tasks are safe to run
• which paths are protected
• which workflow proves the repo is ready
• which failure is a contract signal, not just a command error

Those are not trivia. They are the difference between code editing and repo operation.

Without them, an agent can write a good patch and still leave the repo unverified. It can run a plausible test and miss the actual gate. It can repair local state without updating the assumption that should have lived in the repo. It can follow an old setup path because the repo never promoted the current one into machine-readable truth.

That is why repo contracts matter.

They let the agent stop asking, "What should I try?" and start asking, "What does the repo declare?"

We kept seeing this in real pressure-test repos.

Take a Rails repo like Athena API. The code was not the hard part. The hard part was that the real operating path was split across Bundler hydration, workflow-specific setup, service launch assumptions, and OS-specific behavior.

An agent with a big context window could read:

• a README command
• GitHub Actions YAML
• shell setup fragments
• service assumptions buried in workflow steps

But it still had to guess:

• whether bundle install was the canonical hydration path
• whether Postgres had to be started first
• whether the repo expected native or container execution
• whether the verification path on Windows matched the one on Ubuntu

That is where bigger context stops helping.

The agent does not need one more file. It needs the repo to declare the path.

Once that truth is moved into the contract, the repo can say:

• what setup is canonical
• which workflow is the real verification lane
• which services and readiness checks are required
• which task surface is safe and runnable

That is the difference between “the agent read a lot” and “the agent can operate the repo on purpose.”

A repo contract turns operational knowledge into something humans, CI, and agents can all use.

With Ota, that contract lives in ota.yaml.

It can declare:

• required toolchains and package managers
• dependency hydration paths
• services and readiness checks
• environment files and required variables
• task bodies and safe execution modes
• workflows for setup, verification, and runtime proof
• protected paths and agent-safe tasks
• execution receipts that record what actually ran

The point is not to replace source code, CI, or documentation.

The point is to stop forcing each layer to maintain a separate hidden version of how the repo works.

When repo truth is explicit, an agent can diagnose readiness before acting. CI can run the same workflow the contract declares. A developer can inspect task usage without reading every script. A failure can point back to the assumption that was missing, stale, or violated.

That changes the quality of automation.

If you want the public surface behind that:

• ota doctor explains what is blocked and what to do next
• ota.yaml contract fields declare setup, tasks, workflows, services, and boundaries
• execution receipts record what actually ran and what evidence was collected

Context windows are useful. They help agents inspect more of the repo before making a decision.

But context is not enough to make execution safe.

Execution needs boundaries:

• what can be run
• what should be run
• what must exist first
• what proves readiness
• what evidence should be saved
• what an agent should not touch

Those boundaries need to be declared close to the repo, not reconstructed from a thousand tokens of surrounding text.

This becomes more important as agents move from simple code generation into longer-running repo work: setup, migration, test repair, runtime proof, dependency updates, service orchestration, and CI triage.

At that point, the hard problem is not "can the model see enough files?"

The hard problem is "can the repo explain the right path clearly enough that humans and machines can trust the execution?"

When a repo has no contract, a failed command is often just noise.

Was a dependency missing? Was a service down? Was an env var undeclared? Was the README stale? Did the agent run the wrong task? Did the code break? Did CI use a different path?

Someone has to reconstruct the story manually.

A contract changes that.

If ota up fails, the failure can be treated as a contract signal first:

• a declared prerequisite is missing
• a hidden dependency needs to be encoded
• contract truth drifted from runtime reality
• the selected workflow is not ready on this machine
• the task ran, but readiness did not match the declared surface

That does not make every failure automatic. It makes the failure more useful.

The artifact should not just say "setup failed." It should show what contract was selected, which task or workflow ran, what readiness was expected, what evidence was collected, and which declared assumption needs attention.

That is the difference between command output and repo governance.

The future of coding agents is not only bigger models with more context.

It is repos that can explain themselves.

A good repo should be able to tell an agent:

ota doctorota tasks --useota tasks --safe --useota up --workflow verify --dry-runota run test

And behind those commands, the repo should declare the setup, checks, services, tasks, workflows, and agent boundaries that make those actions trustworthy. That gives the agent something stronger than a long prompt. It gives it a contract.

Bigger context windows help agents read more. Repo contracts help agents act correctly. The useful future is not an agent that can skim every README, shell script, and CI file hoping to infer the right path. The useful future is a repo that declares its operational truth clearly enough that humans, CI, and agents can all follow the same path and produce evidence when it fails. That is why coding agents need repo contracts, not just bigger context windows.