Why agents need a contract

A coding agent should not infer repository setup from scattered hints. It needs the repo to say which tasks are safe, which files are writable, which verification steps matter, and how readiness should be checked.

ota makes those boundaries explicit so the same repo contract can guide humans, CI, and agents.

AI agent repo setup flow

Start with diagnosis, then move through reviewed setup and verification. The agent should operate from the declared contract, not from a guessed sequence of package-manager commands.

prefer declared ota run <task> paths when the repo contract already exposes the setup, verification, or default task you need
drop to raw npm, cargo, pytest, make, or similar commands only for narrow debugging or checks the contract does not model yet
prefer first-class prepare.kind: dependency_hydration over raw install shell when setup truth is dependency hydration ota already owns; that keeps setup intent machine-readable even though the lane usually remains networked and outside routine agent-safe execution
prefer first-class prepare.kind: tool_bootstrap over raw pip install ... shell when the task truth is bootstrapping a required tool such as uv; that keeps tool-install intent machine-readable and distinct from repo dependency hydration
treat declared task effects as execution-risk signals: effects.network means the path is not offline-safe, effects.network_kind can narrow that lane (for example dependency_hydration, integration_test, or tool_bootstrap), and effects.external_state means the path mutates systems outside the repo

Agent-safe first passbash

ota doctorota tasks --jsonota up --dry-runota run testota check --json

What the agent can rely on

Safe tasks

agent.safe_tasks tells automation which repo tasks are approved for unattended execution.

When to use it

Use this when task execution should be explicit instead of left to model judgment.

Example

Writable paths

agent.writable_paths keeps file edits inside the repo surfaces that maintainers actually expect agents to touch.

When to use it

Use this when agent work needs clear filesystem boundaries.

Example

Verification after changes

agent.verify_after_changes declares the checks that should run before an agent hands work back.

When to use it

Use this when code changes need a deterministic validation path.

Example

Machine-readable handoff

Agents and automation should consume JSON output for readiness, tasks, checks, and receipts. That keeps behavior stable even when human-facing wording improves.

use ota doctor --json for blockers and next steps
use ota tasks --json for task inventory and safety hints, including declared task effects
use ota check --json for checks-only readiness gates
use ota run --receipt when execution needs an auditable artifact