Ota gives repositories one explicit contract for readiness, verification, execution, and proof, so humans, CI, and AI agents know what can run and what each result proves.
ota doctor
➜ ready: false
➜ blocker: missing toolchain
ota validate
➜ contract: valid
ota up
➜ setup applied, readiness recheckedThe contract
ota.yaml. One observable result.Ota resolves the declared execution path and reports what ran and what remains unproved.
01 / Declare The contract from the runnable mini-repo
version: 1metadata: ota: minimum_version: "1.6.26"project: name: ota-web type: applicationtoolchains: node: version: ">=22" package_managers: pnpm: "10" fulfillment: source: corepack mode: runtasks: setup: prepare: kind: dependency_hydration medium: package_dependencies source: kind: node_package_manager cwd: . manager: pnpm mode: install requirements: toolchains: [ node ] effects: writes: [ node_modules ] network: true network_kind: dependency_hydration build: depends_on: [ setup ] command: exe: pnpm args: [ build ] requirements: toolchains: [ node ] effects: writes: [ dist ] test: depends_on: [ build ] command: exe: pnpm args: [ test ] requirements: toolchains: [ node ] deploy: depends_on: [ test ] command: exe: pnpm args: [ deploy ] effects: writes: [ release ] safe_for_agent: falseagent: entrypoint: setup default_task: test safe_tasks: [ setup, build, test ] refusal_canaries: - task: deploy protected_paths: [ ota.yaml, .env, .env.local ] verify_after_changes: [ build, test ] 02 / Observe The same contract through Ota
Validate the contract
$ ota validate --plain
VALIDATE ./ota.yaml
VALID
Next:
- run `ota doctor` to inspect readiness
- run `ota tasks --use` to inspect runnable task usage
Inspect readiness
$ ota doctor --plain
DOCTOR ./ota.yaml
READY
Verdict
- Repo: ready
- Agent: ready
AGENT
Overview
- Posture: `readiness_strict`
- Entrypoint: `setup`
- Default task: `test`
Execution
Safe tasks (3): `setup`, `build`, `test`
Verify after changes (2): `build`, `test`
Boundary
Protected paths (3): `ota.yaml`, `.env`, `.env.local`
INFO Selected task path performs network dependency hydration: setup, setup (1)
Why: the selected task path includes tasks with `effects.network_kind: dependency_hydration`; this is a narrower network lane
(for example lockfile-backed package-manager fetches), but still depends on registry reachability
Provenance: repo contract
Next: keep lockfiles and package-manager provenance strict for these tasks, and keep
`effects.network_kind: dependency_hydration` explicit on that path
Discover agent-safe tasks
$ ota tasks --safe --use --plain --concise
TASKS ./ota.yaml
- build
Human Run:
Container: unavailable: not supported by this task
Native (Default): `ota run build`
Agent Run:
Container: unavailable: not supported by this task
Native (Default): `ota run build --agent`
Agent Policy: declared safe; full dependency closure is agent-callable
Preview: pnpm build
Kind: command
Safety Posture: agent-safe routine repo-scoped lane
Effects: writes=dist
Dry Run JSON: `ota run build --dry-run --json`
- setup
Human Run:
Container: unavailable: not supported by this task
Native (Default): `ota run setup`
Agent Run:
Container: unavailable: not supported by this task
Native (Default): `ota run setup --agent`
Agent Policy: declared safe; full dependency closure is agent-callable
Preview: hydrate package dependencies with pnpm install in `.`
Kind: dependency_hydration
Prepare: hydrate package dependencies with `pnpm install` in `.`
Safety Posture: agent-safe lane with networked dependency hydration
Effects: writes=node_modules; network=dependency_hydration
Dry Run JSON: `ota run setup --dry-run --json`
- test
Human Run:
Container: unavailable: not supported by this task
Native (Default): `ota run test`
Agent Run:
Container: unavailable: not supported by this task
Native (Default): `ota run test --agent`
Agent Policy: declared safe; full dependency closure is agent-callable
Preview: pnpm test
Kind: command
Safety Posture: agent-safe routine repo-scoped lane
Dry Run JSON: `ota run test --dry-run --json`
Receipt After Run: `ota receipt --json --archive`
Run the safe test
$ ota run test --agent --plain
RUN SUMMARY
Status: success
Scope: repo
Path: .
Contract: ./ota.yaml
Mode: native
Task: test
Fulfillment: requirements already satisfied for `task:test:native`
Note: running on the host environment
Next: run `ota tasks --use` to inspect runnable task usage
Refuse unsafe execution
$ ota run deploy --agent --plain
AGENT EXECUTION REFUSED ./ota.yaml
ERROR Agent execution refused
Where: ./ota.yaml
Why: task `deploy` is outside the declared agent-safe surface for this contract, so execution was refused before run-path
evaluation
Next: run `ota tasks --safe --use`; review `agent.safe_tasks` / `safe_for_agent`; rerun `ota run deploy --agent` only after
the selected closure is safe
Refusal:
- reason: `requested_task_not_safe`
- task: `deploy`
- mode: `native`
- cause: `agent_safety_boundary`
- closure status: `unsafe`
RUN SUMMARY
Status: blocked
Scope: repo
Path: .
Contract: ./ota.yaml
Mode: native
Task: deploy
Note: running on the host environment
Prove the refusal
$ ota run deploy --agent --expect-refusal
🦦 AGENT REFUSAL CANARY task:deploy
Status: refused as expected
Target: task:deploy
Execution: not started
Reason: requested_task_not_safe
Complete CLI output captured with ota v1.6.28 from the mini-repo shown at left. The safe test executes; the refused deploy and canary do not.
Before vs after
When setup lives outside the contract, readiness is discovered too late and onboarding depends on heroics. Ota moves the diagnosis earlier, so the next safe action is visible before anyone changes a file.
Humans and agents reconstruct setup from READMEs, scripts, manifests, and tribal knowledge.
ota.yaml defines the repository's requirements, setup, supported tasks, and verification paths.
An agent finds a plausible command and guesses whether it is safe or complete.
Ota exposes agent-safe tasks, protected paths, required verification, and refusal boundaries before work starts.
A green local command, CI job, and agent run can each mean something different.
All three use the same contract, so every result can state what ran and what it actually proves.
Clone the repo, read the README, try commands, fix errors, and hope nothing is missing.
Clone the repo, run ota doctor, and get an ordered diagnosis of known readiness gaps before trial and error.
Core commands
ota doctor
Why it matters
Points to the highest-priority blocker or warning and the next safe action instead of guessing at the problem.
When to use it
Use this first when a repo feels broken, incomplete, or inconsistent.
Example
ota validate
Why it matters
Stops bad config before CI, agents, or teammates can rely on it.
When to use it
Use this after editing ota.yaml or before you rely on the contract in CI, onboarding, or automation.
Example
ota up
Why it matters
Lets ota set the repo up through the contract instead of guessing at setup.
When to use it
Use this when the repo should be ready before work starts or before a contract-first run.
Example
ota run
Why it matters
Keeps humans, CI, and agents on the same task the same way every time.
When to use it
Use this after doctor, validate, and up when you want the repo to do real work.
Example
Workflow
Start with ota doctor so the first blocker and the next safe step are visible immediately.
Use ota detect --dry-run and ota init --dry-run to compare the first safe write before ota.yaml exists.
Run ota validate, then ota up --dry-run and ota up to turn contract intent into a ready repo before anyone touches tasks.
ota run executes a task, ota check inspects readiness, and ota proof runtime is the evidence lane when you need to prove one workflow really starts and becomes ready.
Why teams adopt ota
The same contract carries readiness, execution, and evidence across every surface that touches the repository.
ota keeps readiness in ota.yaml, so humans, CI, and agents all read the same source of truth.
Doctor shows the blocker first and the next safe step, so teams move faster with less back-and-forth.
The core loop is repo-local and immediate, so teams get value before any platform rollout.
Supported tasks, writable paths, required verification, and refusal boundaries stay explicit, so AI agents do not have to infer authority from scripts or documentation.
Run ota validate and ota doctor --json in CI to keep the contract honest and the release gate explicit.
Generate AGENTS.md from the same contract so AI agents see the same guidance humans do, without drift.
Prefer ota doctor --json, ota tasks --json, and ota run over scraping prose or guessing at task order, so integrations stay stable.
Ota reports what ran, what was observed, and what remains unproved, so a green result is not mistaken for broader readiness.
Open core
The CLI, repo and workspace contracts, JSON output, docs, and examples stay public under Apache 2.0.
Ota stewards roadmap, releases, schema, JSON, and trust-sensitive command behavior so the public contract stays coherent.
Issues, bug reports, docs feedback, and real-repo reproductions are welcome. External code pull requests are not currently accepted.
Enterprise value should layer on hosted policy, audit, fleet coordination, onboarding, and support without becoming a different contract truth.
For engineering teams
Bring a repository with setup drift, complex CI, or AI-agent execution. We'll show what Ota can govern, what it can prove, and what remains unproved. Contact demo@ota.run.
Start with the right surface
Browse by note type