Repo Setup Automation Should Not Depend on README Drift

Most repo setup automation is still built on a weak assumption:

that the README will stay operationally true.

That is the problem.

Teams add scripts, package commands, Docker files, and CI workflows, but the setup story still starts with:

read the README and do the right thing

That is a weak foundation for automation.

The moment setup truth lives partly in prose and partly in executable surfaces, the repo becomes vulnerable to drift.

The README says one thing. The scripts do another. CI uses a third path. Maintainers know which one is real. Everyone else has to guess.

That is exactly what repo setup automation should eliminate.

My position is direct: if your setup automation still depends on the README as the main carrier of truth, your automation layer is incomplete.

README drift is often described like a docs problem.

It is not just that.

It is an execution problem.

If setup automation is trustworthy, the repo should be able to answer:

• what the setup path is
• what the required runtimes and tools are
• what services must be running
• what task should run next
• what verifies success

If the README is still the place where those answers are primarily explained, then the automation layer is not complete.

It still depends on prose to carry operational truth.

That is why I do not think README-driven setup scales.

It scales until the repo changes.

Then it starts to lie.

Imagine a repo where:

• the README says npm install && npm test
• the actual package manager is now pnpm
• local setup also needs docker compose up -d redis
• CI runs pnpm install --frozen-lockfile, pnpm lint, and pnpm test:ci
• a generated SDK must exist before integration tests pass

That repo can still look reasonably documented.

It is also already drifting.

A new contributor follows the README and gets the wrong package manager, no local Redis, the wrong verification path, and no clue that generated artifacts matter.

That is not a docs typo. That is broken setup automation hiding behind prose.

This is where the difference becomes real.

A README can be much better than that.

It can say:

## Requirements

- Node 22
- pnpm 10
- Docker

## Setup

1. Copy `.env.example` to `.env.local`
2. Start Redis: `docker compose up -d redis`
3. Install dependencies: `pnpm install --frozen-lockfile`
4. Generate SDK: `pnpm generate:sdk`

## Verify

- `pnpm lint`
- `pnpm test:ci`

That is a good README.

But it is still README prose.

A helper script can hide more steps behind a single command.

But neither one gives the repo a clear, inspectable setup contract.

An Ota-backed repo can declare that contract directly:

version: 1project:  name: api-serviceruntimes:  node: "22"tools:  pnpm: "10"env:  sources:    - kind: dotenv      path: .env.local tasks:  setup:env:local:    internal: true    action:      kind: copy_if_missing      from: .env.example      to: .env.local   install:    depends_on:      - setup:env:local    run: pnpm install --frozen-lockfile   setup:    depends_on:      - install    run: pnpm generate:sdk   lint:    depends_on:      - setup    run: pnpm lint   test:    depends_on: [setup, lint]    requires_services:      - redis    run: pnpm test:ci services:  redis:    manager:      kind: compose      name: local      file: docker-compose.yml      service: redis    endpoints:      host:        address: 127.0.0.1        port: 6379    readiness:      from: host      kind: tcp workflows:  default: contributor  contributor:    prepare:      task: setup:env:local    setup:      task: setup    run:      task: test agent:  safe_tasks:    - install    - setup    - lint    - test  protected_paths:    - .env.local    - infra/production

That one contract says much more than even a careful README can guarantee on its own:

• Node 22 and pnpm 10 are declared as repo requirements, not buried in prose
• .env.local is part of the declared setup surface, and Ota can materialize it from .env.example when needed
• the package manager is pnpm, not whatever a stale doc says
• setup is not just install; SDK generation is part of the path
• verification is pnpm lint plus pnpm test:ci, not a weaker local shortcut
• Redis is part of the repo’s declared operating model, service topology, and readiness path
• the contributor front door is explicit
• AI agents have a bounded safe-task surface
• protected paths are declared, not implied

And, importantly, Ota can do something the README cannot:

• validate the contract itself
• diagnose blockers before setup starts
• preview the setup path before mutation
• expose the same truth to humans, CI, and AI agents

Real setup automation should:

• declare requirements explicitly
• make the setup order visible
• make the workflow reproducible
• separate quick local checks from full verification
• expose safe paths for humans and agents
• produce evidence that the repo is actually ready

That is a higher bar than "a script ran successfully."

This is the difference between runnable and trustworthy.

You can automate setup with a shell script and still leave the repo ambiguous.

You can even automate setup in CI and still fail to make the local path clear.

That is why the setup layer needs a contract, not just commands.

This is the core distinction:

• commands tell you what can be executed
• a contract tells you what should be executed, in what order, under what conditions, and how success is verified

That is the difference between automation that runs and automation that can be trusted.

Shell scripts are useful.

They can reduce manual work and bundle repetitive steps.

But they do not naturally answer:

• whether the script is the canonical setup path
• whether a service dependency is required first
• whether the setup succeeded in a meaningful way
• whether the script is safe for automation
• whether a stricter verification path still exists elsewhere

The same is true for package.json scripts, Makefiles, and helper commands.

They can expose actions.

They do not automatically expose execution truth.

Some teams move the real setup logic into CI and treat that as enough.

That is also weak.

CI can prove one environment. It cannot serve as the repo’s only onboarding surface.

If the true setup path only exists in a workflow file, then:

• contributors still have to reverse-engineer it
• local development still drifts
• AI agents still guess from partial signals

CI is proof.

It is not a complete setup contract.

That is the trap: teams mistake a passing workflow for a usable onboarding path.

This is the important line.

READMEs and scripts are useful. They are not enough on their own.

They can document or execute steps. They cannot, by themselves, give the repo a first-class execution contract.

Ota adds things that README-driven setup and helper scripts do not naturally provide:

• one canonical workflow surface instead of competing local and CI paths
• machine-readable readiness and verification
• ota doctor diagnosis before execution starts
• ota up as declared setup instead of undocumented command chains
• dry-run and preview behavior before mutation
• contract validation with ota validate
• safe task boundaries for AI agents
• protected path boundaries for sensitive files and directories
• one shared truth for humans, CI, and agents instead of three parallel interpretations

That is why Ota is not just "better docs" or "nicer scripts."

It gives the repo an execution contract.

The better model is simple:

the repo should declare its setup truth in one explicit place, and every other surface should consume that truth instead of competing with it.

That means:

• the README explains context
• automation follows declared setup
• CI proves declared setup
• agents use declared safe tasks

That is a much cleaner architecture than letting setup sprawl across docs, scripts, and workflow files.

It also creates a much better operating model for the repo, because the project stops looking like a collection of helpful hints and starts behaving like a system with declared rules.

This is where Ota is much stronger than README-driven setup automation.

Ota gives the repo an explicit contract in ota.yaml.

That contract can declare:

• runtimes and toolchains
• setup tasks
• workflows
• readiness checks
• verification tasks
• safe agent boundaries
• writable and protected paths

That changes the repo from:

here are some instructions and scripts

to:

here is the declared contract for how setup and execution work

That is a much more serious model for automation.

In practice, a contract-driven setup path looks like this:

ota validateota doctorota upota run test

That is a better setup standard than:

npm installnpm test

The first sequence gives you contract validity, readiness diagnosis, declared setup, and declared verification.

The second sequence gives you whatever one contributor guessed should happen first.

Then the repo can use:

• ota doctor to explain what is missing
• ota validate to keep the contract honest
• ota up to prepare the repo from declared setup
• ota tasks to expose the declared task surface
• ota run <task> to execute the canonical workflow

This is why Ota is not just another setup wrapper.

It is the contract layer that removes README drift from the center of setup automation.

AI agents expose README drift faster than humans do.

A human can usually work around weak setup with intuition and questions.

An agent follows the strongest visible signal.

If that signal is stale README prose, the agent may:

• install the wrong tools
• skip a required service
• run the wrong verification path
• report success too early
• mutate the wrong surface

That is why repo setup automation now needs to be machine-readable and contract-backed.

The repo should not ask the agent to infer what setup means.

It should declare it.

For example:

agent:  entrypoint: test  default_task: test  safe_tasks:    - install    - setup    - test  protected_paths:    - .env.local    - infra/production  verify_after_changes:    - test

That tells an AI agent something concrete:

• start from test
• install, setup, and test are safe to run
• do not edit .env.local or production infrastructure paths
• verify changes by rerunning test

That is much stronger than telling an agent to "be careful." Ota turns that caution into declared repo policy.

Repo setup automation without README drift is not about writing fewer docs.

It is about putting operational truth in the right place.

The README can still explain the repo.

But it should not be the thing holding the setup model together.

That is what Ota fixes.

It replaces setup folklore and README drift with one explicit, reviewable contract that humans, CI, and AI agents can all work from.

That makes the repo easier to trust, easier to automate, and much easier to hand to a new engineer or an AI agent without crossing your fingers.