One contract instead of README drift
ota keeps readiness in ota.yaml, so humans, CI, and agents all read the same source of truth.
Doctor first. Contract second.
One explicit contract for repo readiness.
ota is an open infrastructure for repo readiness. It gives every repo one explicit contract for readiness, diagnosis, setup, and execution, so humans, CI, and AI agents know the next safe action instead of guessing from README drift.
ota doctor
➜ ready: false
➜ blocker: missing toolchain
ota validate
➜ contract is valid
ota up
➜ setup, checks, readinessCalm diagnostics. Deterministic execution. No guessing.
Why ota exists
One source of truth for repo readiness and first-use confidence.
Deterministic diagnosis
Doctor shows the blocker first and the next safe step, so teams move faster with less back-and-forth.
Useful on day one
The core loop is repo-local and immediate, so teams get value before any platform rollout.
AI-agent-safe by design
Safe tasks, writable paths, verification steps, and execution boundaries stay explicit, so agents can act without guessing.
The problem
Repos are hard to trust when setup lives outside the contract.
Scattered setup becomes guesswork
Without one contract, contributors hunt through README notes, scripts, and old PRs just to make the repo run once.
Local and CI drift apart
What works on one machine often fails on another because the repo never said exactly what it needed.
Readiness is discovered too late
ota moves diagnosis earlier so the next safe action is visible before anyone starts changing files.
Onboarding should not depend on heroics
ota turns the first successful run into a repeatable contract so the repo is easier to trust, share, and revive.
Before vs after
Replace scattered setup with one contract the team can trust.
Before
Setup is scattered across README files, scripts, manifests, and tribal knowledge.
After
One contract tells every developer, CI job, and agent what the repo needs and what the next safe step is.
Before
Clone the repo, read the README, try commands, fix errors, and hope nothing is missing.
After
Clone the repo, run ota doctor, and know what is missing before you waste time.
Before
CI and local development drift quietly over time.
After
Local runs, CI, and agents use the same source of truth, so repo behavior stays consistent.
Core commands
Commands that map to the first real repo decisions.
ota doctor
Shows the current readiness state, blocker, or warning, including the first onboarding blocker when no contract exists.
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.
ota validate
Checks that a contract is sound.
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.
ota up
Prepares a repo for the first run.
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.
ota run
Runs a declared task through the contract.
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.
Workflow
The default path for a real repo.
Review first
Start with ota doctor so the first blocker and the next safe step are visible immediately.
Preview the first contract
Use ota detect --dry-run and ota init --dry-run to compare the first safe write before ota.yaml exists.
Prepare the repo
Run ota validate, then ota up --dry-run and ota up to turn contract intent into a ready repo before anyone touches tasks.
Run and prove
Use ota run, ota check, and ota proof runtime to keep execution, verification, and one real runtime path deterministic.
Example contract
One readable ota.yaml with repo truth and the next safe action.
ota.yamlyaml
version: 1project: name: ota-web type: applicationruntimes: node: "22"tools: pnpm: version: "10" acquisition: provider: corepack package: pnpm version: "10.0.0"tasks: setup: internal: true run: pnpm install safe_for_agent: true build: depends_on: [setup] run: pnpm build test: depends_on: [build] run: pnpm testagent: entrypoint: setup default_task: test safe_tasks: [setup, build, test] protected_paths: [ota.yaml, package-lock.json, .env] verify_after_changes: [build, test]Why teams adopt ota
Useful for humans, CI, agents, and automation from the first repo.
CI and Pipelines
Run ota validate and ota doctor --json in CI to keep the contract honest and the release gate explicit.
AI agents
Generate AGENTS.md from the same contract so AI agents see the same guidance humans do, without drift.
Automation
Prefer ota doctor --json, ota tasks --json, and ota run over scraping prose or guessing at task order, so integrations stay stable.
Enterprise later, open core now
Hosted policy, audit, support, and fleet coordination come later as a layer around the open core, not as a replacement for it.
Open core
Public core, explicit governance, contribution policy up front.
What is open
The CLI, repo and workspace contracts, JSON output, docs, and examples stay public under Apache 2.0.
How governance works
Ota stewards roadmap, releases, schema, JSON, and trust-sensitive command behavior so the public contract stays coherent.
Contribution policy
Issues, bug reports, docs feedback, and real-repo reproductions are welcome. External code pull requests are not currently accepted.
Enterprise boundary
Enterprise value should layer on hosted policy, audit, fleet coordination, onboarding, and support without becoming a different contract truth.
Get started
Start with doctor, not guesswork.
Read the docs, install the CLI, and make the repo contract the source of truth before you write or run anything.