Start from discovery

Before acting in a repo, an agent should load the public ota discovery surfaces, then switch to the repo-local contract.

Public discoverytext

https://ota.run/llms.txthttps://ota.run/llms-full.txthttps://ota.run/docs/index.jsonhttps://ota.run/openapi.json

Inspect the repo contract

Inside the checkout, prefer ota commands over inferred package-manager commands when ota.yaml exists.

First local passbash

test -f ota.yaml && ota doctor --jsonota validateota tasks --json

copy the nearest example contract only when the repo lacks ota.yaml
customize the smallest required fields for runtimes, setup, services, and tasks
validate before writing broader changes
execute only declared safe tasks unless the user explicitly approves a broader command
parse JSON output instead of scraping terminal prose

Agent-safe flowbash

ota detect --dry-run .ota init --dry-run .ota validateota up --dry-runota run test --json

stop when ota doctor reports blockers that require user secrets, credentials, or external services
stop when a task declares external state and the user has not approved mutation
stop when writable paths or safe tasks do not cover the requested edit
report the exact command, JSON status, and next safe action