Most repositories are built for people who already know them.

That works for a while. The maintainer remembers which setup step matters. The team knows which script to run first. Someone understands why the README says one thing but CI does another. The repo is "runnable," but only because enough context lives outside the repo itself.

That model is starting to break.

More software work now happens through systems that do not have that context: CI jobs, ephemeral dev environments, remote runners, automation scripts, and coding agents. They do not know the history of the repo. They cannot ask the maintainer what changed last week. They need the repo to explain itself.

Not just what files it contains, but how it becomes useful.

That is what I mean by repository readiness.

A ready repo should be able to answer:

• what do I need installed?

• what environment values matter?

• what setup steps are required?

• which commands are safe to run?

• what does success look like?

• what should happen when something is missing?

Today, those answers are usually scattered across docs, scripts, CI files, package metadata, Docker config, and memory. Each piece may be correct on its own, but there is rarely one explicit place that defines the working state of the repo.

Ota is our attempt to make that working state explicit.

The idea is simple: a repo should have a readiness contract.

That contract should be readable by humans, but structured enough for tools to use. It should tell a developer what is missing. It should tell CI what was verified. It should tell an agent what it can safely run. And it should make drift easier to catch when the repo changes.

The first version of that is a small CLI flow:

ota doctor
ota up
ota run <task>

ota doctor asks: what is blocking this repo from being ready?

ota up asks: what needs to be prepared?

ota run asks: what task should run through the declared repo contract?

The point is not to replace existing tools. Repos already have package managers, Docker files, Makefiles, dev containers, CI workflows, and setup scripts. Ota should sit above those and make the operational path visible.

Because the real problem is not that repos lack tools.

The problem is that the meaning of those tools is often implicit.

A script named dev might start the app. Or only the frontend. Or require a database that nobody mentioned. A README might be right when written and wrong three months later. CI might validate a path that local contributors never use. An agent might run a command that looks obvious but is not actually safe.

Humans work around that with memory and conversation.

Machines need a contract.

That is why I think repo readiness needs to become machine-readable. Not as a nice extra, but as part of the repo's operational surface.

If software is going to be built by a mix of humans, CI, automation, and agents, then the repo needs to expose more than source code. It needs to expose the path to a trustworthy working state.

That is what we are building with Ota.

Project: https://github.com/ota-run/ota

Examples: https://github.com/ota-run/examples

If you maintain a repo where setup has drifted, onboarding is painful, or the "right way to run it" lives mostly in people's heads, I'd love for you to try Ota. I'm also happy to help draft the first ota.yaml for a real repo.

What do you think repos still need before they are truly machine-readable?