Short answer

README-first onboarding drifts because prose, scripts, CI jobs, Docker files, and local conventions all change at different speeds. The repo stops having one trustworthy first-run path.

Makefiles, package scripts, shell scripts, Docker Compose files, Devbox projects, Nix flakes, and CI workflow files are useful operational surfaces. ota is the repo readiness contract around those surfaces.

Where README-first setup breaks down

README prose

Explains what used to be true, but usually cannot prove the repo still works that way today.

When to use it

Use prose for orientation, not as the only source of setup truth.

Example

Setup scripts and Makefiles

Give contributors a shortcut, but rarely explain whether prerequisites, services, network effects, or verification steps are complete.

When to use it

Use them for ergonomics once the real readiness boundary is already explicit.

Example

CI workflows

Show how automation runs on one hosted lane, not necessarily what a fresh contributor or coding agent should do locally first.

When to use it

Use them for orchestration, permissions, matrices, and deployment gates.

Example

What each layer answers

Makefile or package script

Answers which command shortcut to run.

When to use it

Use it for local ergonomics when the setup, dependencies, and service state are already obvious.

Example

CI workflow

Answers how automation should run on a hosted runner.

When to use it

Use it for triggers, matrix jobs, permissions, artifacts, environments, and deployment gates.

Example

Docker Compose, Devbox, or Nix

Answers how to provision an environment or service topology.

When to use it

Use these when the repo needs a reproducible shell, container stack, package set, or local infrastructure.

Example

ota

Answers whether the repo is ready, what must be true before a task runs, and which operations are safe for humans, CI, and agents.

When to use it

Use it when setup, validation, and task semantics need to be explicit and machine-readable.

Example

What contract-first onboarding changes

Contract-first onboarding gives the repo one explicit operating source of truth. Instead of asking every contributor to reconstruct setup from prose and side effects, the repo declares its runtimes, tools, services, tasks, writable paths, and verification flow in ota.yaml.

That changes the first-run experience from 'read, guess, try, fix' into 'diagnose, review, prepare, run'.

Contract-first onboardingbash

ota doctorota validateota up --dry-runota upota run test

Why agents need more than scripts

AI coding agents can call scripts, but scripts rarely explain whether they mutate external state, require network access, depend on services, or count as trusted verification.

ota exposes those boundaries through the contract and JSON output so an agent can diagnose first, choose a declared task, and validate the change without inventing a workflow.

Agent-safe flowbash

ota doctor --jsonota tasks --jsonota up --dry-runota run test

Adoption path

keep existing scripts where they already work
stop treating README prose as the source of truth for first-run setup
add ota.yaml to declare readiness, tasks, services, and agent boundaries
use ota validate in CI before expensive jobs
move agent and automation handoff to ota tasks --json, ota run, and execution receipts