Short answer

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

A repo can keep its existing scripts and still use ota to declare runtimes, setup, services, task safety, writable paths, verification, JSON output, and execution receipts.

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

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
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