DEV Community: Bobai Kato

Why Developer Onboarding Should Be Contract-First

Bobai Kato — Mon, 08 Jun 2026 14:16:52 +0000

Overview

Most developer onboarding is still operationally weak.

A new engineer clones a repo, opens the README, installs dependencies, runs the obvious command, and still ends up blocked because the real setup path lives somewhere else.

Maybe CI is stricter than local. Maybe a service has to be running first. Maybe the package manager changed. Maybe generated files are required. Maybe the README test path is not the path that actually matters.

That is not just onboarding friction.

It means the repo never declared its onboarding truth clearly enough.

My view is simple: developer onboarding should be contract-first.

A repo should declare how onboarding actually works instead of asking every contributor to reconstruct it from prose, shell history, CI YAML, helper scripts, and maintainer folklore.

That is one of the strongest reasons Ota exists.

Why Developer Onboarding Still Breaks

Most repos are still onboarded through a loose mix of:

README instructions
shell scripts
package manifests
CI workflows
.env.example files
tribal knowledge

Each one may be useful.

Together they often create ambiguity.

A new contributor should not need to answer all of these by inference:

which runtime version is required
which package manager is canonical
which services must be running
whether setup is already complete
which command is the real verification path
which tasks are safe to run
what counts as done after a change

If the repo does not answer those questions explicitly, onboarding becomes a debugging exercise.

What “Contract-First” Actually Means

Contract-first onboarding does not mean "write more docs."

It means the repo has one explicit place where its operational truth is declared.

That contract should define:

what the repo needs
how it becomes ready
which tasks exist
which workflows are canonical
what verifies success
what is safe for automation and AI agents

That is the shift.

From:

Here are some instructions. Good luck.

To:

Here is the declared operating model for this repo.

That is a materially better onboarding standard.

It also happens to be the standard that scales to CI and AI agents instead of only to patient humans.

Why README-First Onboarding Breaks Down

README-first onboarding works only while the repo is simple and slow-moving.

Once the repo evolves, drift shows up fast:

local commands diverge from CI
scripts encode setup details the README never explains
new services appear without being declared clearly
generated artifacts become part of the build
maintainers silently know which path is the real one

That means the README may still get someone to a runnable state without getting them to a trustworthy one.

A contributor may pass one local check and still miss the actual verification standard.

That is why contract-first onboarding is stronger.

It is not just about starting work.

It is about starting work from the same truth the repo expects later in CI, review, and automation.

A Repo-Shaped Onboarding Failure

Imagine a new engineer joining a repo where:

the README says pnpm install && pnpm test
CI runs pnpm install --frozen-lockfile, pnpm lint, pnpm typecheck, and pnpm test:ci
local development actually depends on docker compose up -d postgres
generated client files must exist before the app boots cleanly

The engineer follows the README, gets one green result, and still hands off work that fails in CI.

Nothing about that failure is exotic.

The repo simply never declared its onboarding truth in one place.

That is the kind of issue maintainers often dismiss as "just onboarding friction." It is more serious than that. It means the repo is teaching new contributors the wrong standard on day one.

Why Ota Is The Right Layer

Ota gives repos an explicit contract in ota.yaml.

That matters because onboarding should not be a side effect of scattered tooling.

It should be a first-class part of repo readiness.

With Ota, the repo can declare:

setup
toolchains and runtimes
tasks
workflows
readiness checks
verification expectations
safe agent boundaries
protected and writable paths

That makes onboarding much stronger for:

new developers
maintainers
CI
AI agents

The same contract can then be used through commands like:

ota doctor
ota validate
ota up
ota tasks
ota run <task>

That is the real difference.

Ota does not just document onboarding.

It turns onboarding into executable repo policy.

That is a much better model than hoping the right shell script, README paragraph, and CI workflow all happen to stay aligned.

The Practical Difference

Old onboarding looks like this:

read the README
install what seems right
run the obvious command
inspect failures
ask a maintainer
check CI to see what was missed

Contract-first onboarding looks like this:

inspect readiness
see what is missing
follow the declared setup path
run the declared task
verify against the declared standard

That is not just cleaner.

It is more trustworthy.

It is also easier to review, easier to automate, and much easier to hand to an AI agent without hoping it reconstructs the right path from scattered clues.

In Ota terms, a responsible onboarding sequence looks like:

ota validate
ota doctor
ota up
ota run test

That is a much better standard than:

pnpm install
pnpm test

The first sequence tells you whether the repo contract is valid, whether the repo is blocked, what setup path should run, and what verification task actually matters.

The second sequence only tells you what one contributor guessed first.

Why This Matters More With AI Agents

AI agents make weak onboarding much more visible.

A human can ask follow-up questions or rely on intuition.

An agent follows the strongest signal it can find.

If the repo does not declare its onboarding contract clearly, the agent starts guessing:

which command to run
whether setup happened correctly
whether a service is required
whether a quick pass is enough
whether a task is safe

That is why contract-first onboarding is not just a developer-experience idea anymore.

It is an execution-governance idea.

The better the onboarding contract, the more trustworthy the repo becomes for both humans and agents.

Closing

Developer onboarding should not depend on luck, folklore, or whoever happens to remember the setup order this week.

The repo should declare how it becomes ready.

That is what contract-first onboarding means.

And that is why Ota is a stronger answer than another README paragraph or another helper script.

It turns onboarding from scattered guidance into a declared, reviewable, reusable contract.

That is the kind of onboarding standard that makes a repo feel serious the first time someone touches it.

Originally post here: https://ota.run/blog/why-developer-onboarding-should-be-contract-first

Pressure-testing Ota on Discourse: repo-wrapper truth matters more than a passing bundle command

Bobai Kato — Sat, 06 Jun 2026 22:15:01 +0000

Overview

Discourse turned out to be a good pressure repo for a narrow but important reason:

the difference between bundle existing and the repo's real Bundler path being truthful is not cosmetic.

This repo already had a wrapper at bin/bundle. That wrapper is part of how the repo expresses and activates its Bundler lane. If a readiness contract ignores that and just says "run bundle", it is not preserving repo truth. It is flattening it.

That is exactly the kind of thing pressure testing should catch.

Before Ota

Before the contract was tightened, the repo already had real working paths:

Ruby and Bundler were core to the baseline contributor surface
the repo shipped a Bundler wrapper
the container path depended on the repo-owned dev image

The problem was not that the repo lacked commands. The problem was that a naive contract can choose the wrong command and still look plausible.

That is dangerous because a readiness contract is supposed to make execution semantics more honest, not more generic.

The mistake that mattered

The key contract mistake was simple:

using plain bundle ...
instead of the repo wrapper bin/bundle ...

That looked harmless until it was pressure-tested through real execution.

It was not harmless.

The wrapper is where repo truth lives. It is what ties command execution back to the Bundler lane the repo actually expects. If the contract bypasses it, then the contract is no longer modeling the repo. It is modeling an easier parallel story.

That is the wrong standard.

What Ota had to learn

Discourse also exposed a real Ota product gap.

Ota initially treated the Bundler ownership/version surface too literally around the executable name. The contract could declare Bundler truth, but execution and diagnosis still needed to understand that bundle is the real command surface for Bundler, and that a repo-local wrapper like bin/bundle is not the same thing as a global host tool.

That pressure produced two useful fixes:

Bundler alias/version truth had to stay attached when the executable path was bundle
repo-local executables like bin/bundle could not be inferred as global host tools

Those are the right product fixes. They belong in Ota, not in repo-local workarounds.

The final contract shape

The cleared Discourse slice is intentionally narrow.

It models:

baseline Ruby and Bundler verification
repo-wrapper-based Bundler truth through bin/bundle
native and container verification on the repo-owned dev image

It does not claim the broader mixed Ruby plus pnpm frontend pressure lane in the upstream-ready branch.

That matters.

A pressure branch can explore broader surfaces. A PR-ready contract should only claim what has been proven and what the repo should actually own as a stable readiness path.

For Discourse, the honest baseline is the Ruby and Bundler slice.

What the matrix now proves

The matrix is doing the right kind of work:

ota validate
ota doctor
ota tasks --use
native dry-runs
container dry-runs
native execution
container execution
workflow verification through the declared verify path

That gives us something stronger than a contract that merely parses.

It proves that the contract and the repo agree about the baseline execution surface they are claiming.

Why this repo is worth writing about

Discourse is a good example of a subtle but important rule:

repo readiness is not just about whether a command works. It is about whether the contract preserves the command boundary the repo itself depends on.

If a repo ships a wrapper because that wrapper carries real execution meaning, the contract should model that wrapper. It should not sand it down into a generic command just because the generic command feels simpler.

That is where readiness tooling either becomes infrastructure or stays documentation theater.

This pass pushed Ota in the right direction:

keep executable truth attached to repo-owned tool semantics
respect repo-local wrappers when they are part of the real path
keep the upstream contract on the narrower proven slice instead of over-claiming a broader mixed-stack story

That is the standard pressure testing should enforce more often.

Ota vs Dev Containers

Bobai Kato — Thu, 04 Jun 2026 20:07:47 +0000

Overview

Ota vs Dev Containers sounds like a straightforward tooling comparison.

It is not.

They solve different problems, and teams get confused when they expect one to do the other job.

Dev Containers package an environment.

Ota defines repo truth.

That is the cleanest way to understand the difference.

If your problem is "how do I give contributors and agents a consistent containerized workspace?", Dev Containers are a strong answer.

If your problem is "how does this repo declare what it needs, how it becomes ready, what tasks are canonical, what verifies a change, and what is safe for an agent to run?", Dev Containers are not enough.

That is where Ota belongs.

What Dev Containers Are Actually Good At

Dev Containers are good at packaging a development environment.

They help define:

base image and operating system
runtime and tool installation
editor extensions and workspace defaults
container-first development assumptions
a more consistent shell for local and hosted workspaces

That is useful.

If a repo depends on a specific Node version, Python version, OS library, CLI, or container-based workspace shape, a devcontainer can reduce a lot of "works on my machine" variance.

For AI agents, that also matters. A better environment reduces wasted time on missing host dependencies and wrong local assumptions.

But environment packaging is not the same thing as repo readiness.

That is where teams over-credit Dev Containers.

What Dev Containers Do Not Solve

A devcontainer does not, by itself, answer:

which task is the canonical verification path
whether setup must happen before test
what safe tasks an agent is allowed to run
which paths are protected
which service dependencies are required for a workflow
what counts as readiness
what should happen after a code change

That is not a failure of Dev Containers. It is simply not their job.

A devcontainer can say:

"Here is the environment you should work inside."

It does not usually say:

"Here is the contract for how this repo becomes ready, which workflow is canonical, and what proves the work is done."

That gap matters a lot for AI agents.

What Ota Solves Instead

Ota is not trying to replace environment packaging.

Ota solves the harder repo-level problem:

what the repo needs
how setup happens
which tasks exist
which workflow is canonical
what counts as readiness
what is safe for an agent to run
what should be verified after changes
which paths are writable or protected

That contract lives in ota.yaml.

This is the difference in operating model.

A devcontainer gives you a place to work.

Ota tells you how the repo works.

That is why Ota matters more once teams start caring about CI alignment, contributor onboarding, agent safety, and execution truth.

The Wrong Comparison

The wrong question is:

"Should I use Ota or Dev Containers?"

That is like asking whether you should use a blueprint or a workshop.

You can absolutely use both.

In fact, that is often the stronger setup:

Dev Containers define the containerized workspace
Ota defines the repo contract that humans, CI, and agents consume inside that workspace

That is the architecture that actually scales.

The repo gets a consistent environment and a consistent execution model.

Why This Matters For AI Agents

AI agents do not just need the right binaries installed.

They need the repo to stop making them guess.

A devcontainer can reduce environment confusion, but an agent can still fail badly inside a perfect container if the repo does not declare:

which task to run first
whether a service must be ready
whether test is enough or ci is required
whether a build must happen before verification
whether certain paths are off-limits

That is why "we have a devcontainer" is not the same as "the repo is ready for agents."

It is only one layer.

Ota is the layer that makes the repo legible to automation.

With Ota, the agent can use commands like:

ota doctor
ota validate
ota up
ota tasks
ota run <task>

That gives the agent more than a shell.

It gives the agent declared execution truth.

Concrete Example

Imagine a repo with a strong devcontainer:

the right Node version is installed
Docker is available
editor tooling is configured
shell dependencies are ready

That is good.

But the agent still needs to know:

should it run pnpm test, pnpm test:ci, or make check?
does Postgres need to be started first?
is build part of the verification contract?
is the agent allowed to touch generated files?

The devcontainer does not answer those questions well.

An Ota contract can.

That is why Ota is not competing with the devcontainer feature itself. It is governing the repo behavior inside and beyond that environment.

What Ota Adds On Top Of Dev Containers

If you already use Dev Containers, Ota adds the missing control plane.

Ota can define:

setup workflow
readiness checks
task boundaries
safe agent tasks
protected paths
verification after changes
native versus container posture

That means the repo can finally stop relying on:

README prose as setup truth
CI YAML as the only authoritative workflow
maintainer memory as the approval system for risky commands

This is why I do not describe Ota as "another environment tool."

It is execution governance.

That is the layer most repos are still missing.

When Dev Containers Are Enough

Dev Containers may be enough on their own if:

the repo is small
the environment is the main source of friction
task truth is still simple
agent safety is not yet a real concern
contributors can still reason about the workflow without much ambiguity

That is a real use case.

But once the repo has:

multiple workflows
service dependencies
local versus CI drift
partial setup folklore
AI agents doing real changes

the problem has outgrown environment packaging alone.

That is when Ota becomes the more important layer.

So, Ota or Dev Containers?

If you only want a containerized development environment, Dev Containers are the right answer.

If you want the repo to declare how it becomes ready, how work runs, what verifies success, and what agents may safely do, Ota is the right answer.

If you want both environment consistency and execution truth, use both.

But if you force me to answer which one matters more for AI-agent repo readiness, the answer is Ota.

Agents can survive a less polished environment better than they can survive an ambiguous repo.

Environment mistakes waste time.

Execution ambiguity destroys trust.

Closing

Dev Containers are useful.

They solve a real problem.

But they do not solve the whole repo-readiness problem, and teams should stop pretending they do.

Ota solves the harder, more strategic layer: repo truth.

That is the layer that tells humans, CI, and agents what the repo needs, how it becomes ready, how work should run, and what counts as done.

That is why Ota is not an alternative to Dev Containers in the simple sense.

It is the stronger answer to the bigger problem.

Originally post here: https://ota.run/blog/ota-vs-devcontainers-2n7d

Pressure-testing Ota on Osiris: making runtime proof and Docker paths honest

Bobai Kato — Thu, 04 Jun 2026 00:05:43 +0000

Overview

Osiris was a useful pressure repo because it looks like a lot of real application repos: a Next.js app, a documented Docker Compose self-host path, no canonical npm test, and a lint surface that exists but is not currently clean enough to claim as the default verification path.

That combination is exactly where readiness tools get exposed. It is easy to make a contract that parses. It is harder to make one that tells the truth.

Before Ota

Before the contract was tightened, the repo had the usual problems:

install, dev, build, start, and Docker flows existed, but the readiness truth was split across README.md, DOCKER.md, Dockerfile, docker-compose.yml, and package scripts
there was no honest way to claim a default test task, because the repo does not define one
lint was visible, but not a truthful default verification gate because the current upstream baseline is red
Docker Compose was documented, but that did not automatically mean the Docker engine should be modeled as a repo service

That last point mattered. A lot of tooling gets this wrong and starts inventing fake service models instead of separating host capability from repo runtime.

What we modeled

The final contract does not pretend the repo is cleaner than it is. It models the repo that actually exists today:

a host-native Node path for install, typecheck, build, dev, and start
an Ota-managed container path for install, verify, dev, and start
a detached Docker Compose self-host path that matches the repo docs
a bounded verify task that proves typecheck + build, not a fabricated test
an explicit empty agent-safe surface, because this slice depends on dependency hydration and runtime-state mutation

The contract also moved Node ownership to toolchains.node, while keeping npm as a standalone tool. That is the honest shape for Osiris: the repo clearly needs Node 22, but it does not declare a first-class Corepack-managed package-manager lane in repo metadata.

What Osiris exposed in Ota

Osiris surfaced two real Ota product gaps.

1. Detached native external-state starters were misclassified

The repo’s documented Docker path is:

docker compose up -d

That is a detached starter. The process exits cleanly while the runtime continues in Docker.

Older Ota behavior treated that like a failed service run if the endpoint was not yet reachable before the starter exited. That is the wrong execution model. A detached external-state starter is not the same thing as a foreground process that crashed.

2. Runtime proof treated warning-only doctor reports as failure

Once the Docker runtime was actually up, Ota could still fail runtime proof because doctor emitted warning-only findings around declared external-state mutation.

That is also the wrong trust model. Warning-only doctor output should still allow runtime proof to succeed when readiness is genuinely proven.

What changed

Osiris drove platform fixes, not repo-local glue.

detached native starters that explicitly mutate external state are no longer misclassified as failed service runs just because the starter process exits before readiness is observed
runtime proof no longer fails when readiness is proven and the remaining doctor findings are warnings rather than blockers

The Osiris contract also got materially stronger:

toolchains.node now owns the Node requirement
verify is explicit and honest: typecheck + build
the nonexistent test surface is not invented
Docker Compose stays modeled as the documented runtime path, not a fake attached dev flow
Docker engine availability is expressed as a host precondition check, not as a fake repo service
protected paths and agent notes are tighter and clearer

That produces a better contract for both humans and agents. A contributor can see the canonical paths quickly. An agent can see what is safe, what is bounded, and what still depends on external state.

What the matrix now proves

The final matrix does more than check that ota.yaml parses.

It now covers:

ota validate
ota doctor as a diagnostic surface
ota tasks --use
ota tasks --safe --use
workflow dry-run coverage
task dry-run coverage
representative native execution
representative container execution
optional runtime-proof lanes for the heavier runtime surfaces

That is the right level of proof for this repo. It keeps CI meaningful without turning every PR into a slow full-runtime gauntlet.

Why this matters

Osiris was a good reminder that repo readiness is not just about command discovery.

The hard part is telling the truth about execution:

what the real verification surface is
whether Docker is a repo service or a host capability
whether a detached starter succeeded or failed
whether runtime proof is actually proving readiness or just reacting to warning noise

Those are not documentation problems. They are infrastructure trust problems.

Pressure-testing Osiris made Ota better in exactly the places that matter most: execution semantics, runtime proof, and honest contract boundaries.

After this work, a new contributor or agent no longer has to infer which Osiris path is canonical from scattered docs and commands. They can inspect the declared surface with ota tasks --use, validate the contract with ota validate, diagnose readiness with ota doctor, and choose the host-native, container, or documented Docker self-host path on purpose.

Pressure-testing Ota on OpenHands: from setup fragmentation to execution governance

Bobai Kato — Mon, 01 Jun 2026 10:07:47 +0000

Overview

OpenHands was a useful repo to pressure-test because it is not a toy. It has a Python backend, a frontend dev server, a standalone openhands-ui package, a documented Docker runtime path, and enough setup branching to create false confidence if you only read the docs.

You can usually get OpenHands working by reading Development.md carefully and filling the gaps from habit. That is not the bar. The bar is whether local development, CI, and an agent can choose the same path without guessing.

That was the real question behind this pressure test:

Can one contract make path selection explicit enough that a human, CI job, and coding agent all hit the same operating surface on purpose?

Why OpenHands was a strong test

OpenHands already has strong docs. The problem was not missing documentation. The problem was that the repo's real operating model was spread across too many places:

Development.md explained the happy path
Makefile carried real execution behavior
workflow YAML encoded what CI actually trusted
maintainer memory filled in the rest

That split matters because OpenHands has multiple valid ways to run:

a host-native contributor path with Python, Node, Poetry, and INSTALL_DOCKER=0
a documented Docker wrapper path through make docker-run
a packaged container path that is better modeled as a first-class container service
a separate openhands-ui package that uses Bun instead of the main app toolchain

That is exactly where readiness drift starts. Nothing is obviously broken, but the repo still makes people infer too much.

Where the repo actually fought back

Three things made this a real test instead of a cosmetic one.

First, "run the app" was not one thing. The host-native GUI loop and the Docker runtime loop are both legitimate, but they serve different needs. If they are collapsed into one vague app workflow, the contract becomes decorative instead of operational.

Second, openhands-ui is not just "more frontend." It has its own Bun-based build surface and lockfile. Treating it like part of the main frontend/ path would make the contract easier to write and less truthful.

Third, some of the repo's important assumptions live in environment toggles and context, not just task names. INSTALL_DOCKER=0, RUNTIME=local, host-only constraints, and container execution mode are all easy for a maintainer to remember and easy for an agent to miss.

That is the class of repo where Ota has to do more than list commands. It has to make execution intent legible.

What changed

The result was a narrower but much more explicit readiness contract:

contexts that separate host-dev, docker-host, host-ui, and the ephemeral app container path
workflows for app, backend, frontend, app:docker, app:container, and ui-package
explicit surfaces for backend, frontend, and packaged-web
a matrix that checks contract validity, dry-run behavior, real task execution, and runtime proof without pretending those are the same signal
pinned Ota install and contract minimum version on v1.6.18

The contract decisions that mattered

The important part was not "we added more workflows." The important part was drawing boundaries that match how the repo actually behaves.

app is the canonical local GUI workflow. It follows the documented self-development path and exposes backend and frontend readiness separately.
app:docker stays tied to the repo's own make docker-run wrapper. That matters because it preserves the documented runtime path instead of replacing it with Ota opinion.
app:container models the packaged image as a direct Ota-managed container service. That gives a cleaner surface when you want the packaged runtime itself, not the repo wrapper around it.
ui-package stands on its own because the Bun-based openhands-ui package is a distinct build surface, not just an implementation detail of the main frontend loop.

Those distinctions look fussy until you try to automate the repo. Then they are the difference between "agent can run something" and "agent can choose the right thing."

Before and after

Before:

follow docs and infer which path you actually mean
manually reconcile host-native, Docker-wrapper, and packaged-container behavior
treat CI workflow behavior as proof of intent after the fact
rely on maintainer memory for which tasks are safe to dry-run, safe to execute, or meaningful for agents

After:

choose a declared workflow that already encodes the intended path
dry-run that path before mutating anything
validate readiness through named surfaces instead of log inspection
keep agent execution bounded by declared tasks, modes, and safety labels

Why the matrix had to be opinionated

One of the most useful outcomes here was not in ota.yaml. It was in the matrix design.

The generic "execute non-internal non-runtime tasks" loop intentionally excludes category: test.

Why:

OpenHands has aggregate test surfaces that can fail for reasons unrelated to basic repo readiness
the generic execution lane should prove that the contract is runnable, not collapse into a catch-all CI job
deterministic signal is more valuable than noisy completeness in a pressure matrix
tests still run in dedicated verification lanes like lint:backend, lint:frontend, and test:backend

That split matters. If every lane means everything, the matrix stops teaching you anything. Here the lanes do different jobs on purpose: validation, dry-run topology, safe execution coverage, and runtime proof.

Takeaway

OpenHands was useful because it forced Ota to be specific.

The repo already had commands. It already had docs. It already had CI. What it did not have was one machine-checkable contract that said:

this is the native contributor path
this is the documented Docker path
this is the packaged container path
this is the separate UI package path
these are the surfaces that prove each one is actually ready

That is the difference between command wrapping and execution governance.

OpenHands did not just give Ota a nice demo repo. It forced the contract to carry real operational distinctions that contributors and agents usually keep in their heads. That is exactly the kind of pressure test Ota needs.

Get Started with Ota

Install: ota.run/docs/install
Contract reference: ota.run/docs/reference/contract
Command reference: ota.run/docs/reference/command
Workflow modeling: ota.run/docs/reference/workflows

ota doctor
ota validate .
ota tasks --use
ota up --workflow app --dry-run .

Originally posted here: https://ota.run/blog/pressure-testing-ota-on-openhands-2q9k

The Ota Skill for AI Agents

Bobai Kato — Fri, 29 May 2026 18:34:38 +0000

Overview

We built the Ota skill because too much "AI repo automation" is still fake confidence.

An agent clones a repo, finds a plausible command, edits the right file, and looks smart right up until it does something expensive and stupid. It runs the wrong test path. It installs tools globally because local setup was unclear. It patches around a missing service as if the repo were healthy.

That failure is usually blamed on the model. Most of the time it is a repo problem. The repository never made its real operating path explicit enough for the agent to follow without guessing.

Ota already gives the repo a machine-readable contract through ota.yaml. The skill exists to teach agents how to behave around that contract: what to trust, what to run, and when to stop instead of improvising.

It is not a replacement for ota.yaml. It is not an MCP server. It is not a hidden automation layer.

It is the missing operating guide for agents working in Ota repos.

Why an Ota skill exists

We kept seeing the same pattern: the agent was fast, but the repo was vague.

Without a repo-specific operating guide, an agent may see several possible paths:

run the command from the README
copy the command from CI
infer setup from package.json, pyproject.toml, or go.mod
run a broad test command because it looks conventional
install tools globally because a local command failed
patch around a missing service instead of identifying the readiness gap

Some of those choices work. Some are dangerous. Some look fine locally and still miss the only verification path that matters.

Our view is simple: if a repo has ota.yaml, that file should beat README prose, shell folklore, and whatever command happens to look familiar. Declared tasks, writable paths, setup requirements, and validation commands should be treated as contract facts.

The skill exists to make that behavior explicit across agents that support skills.

What the skill teaches an agent

The official skill lives in ota-run/skills. It is aimed at the work that actually shows up in live repos:

authoring or refining an ota.yaml contract
reviewing an existing contract for drift or weak boundaries
running ota doctor, ota validate, ota tasks, and ota run
deciding whether a problem belongs in the repo contract or in Ota itself
preserving safe execution, writable path, and setup boundaries
explaining repo readiness issues in terms humans can act on

What matters is not the length of the skill. What matters is the order it forces on the agent.

In an Ota repo, the agent should start from the contract, not from vibes. It should prefer declared tasks over shell improvisation. It should use JSON output when automation needs stable facts. It should not invent fields, flows, or setup steps the repo never declared.

That sounds obvious. It is also where a lot of agent work still goes off the rails.

The contract still comes first

The skill does not rescue a sloppy repo.

Readiness still belongs in the repo. The repo needs to state what it requires, how it becomes ready, what commands exist, and how those commands are verified. That is the job of ota.yaml.

The skill tells the agent how to behave around that contract.

For example, if a repo declares a test task through Ota, the agent should use ota run test instead of guessing at npm test, pytest, or go test ./.... If the repo exposes ota doctor, the agent should use it to understand readiness before mutating files. If the repo has writable path boundaries, the agent should treat those boundaries as real, not as suggestions.

This matters because AI-assisted development usually fails at the edges:

setup was incomplete
a service was missing
the agent ran the wrong verification command
a generated file was edited directly
a one-off shell command bypassed the repo's intended workflow
a local success did not match CI

What it does do is keep the agent anchored to the same contract humans and CI are supposed to trust.

Installing the skill

Agents and environments can consume skills differently. The current supported install paths are:

npx skills add ota-run/skills --full-depth

ota skills install --agent codex
ota skills install --agent claude

The ota-run/skills repository is the source of truth for the skill distribution. ota skills install gives Ota a first-party install path for supported agent environments, and the skills CLI path supports workflows that consume skill repositories directly.

The site also exposes discovery links for agents:

Those URLs are intentionally boring. Discovery should not be the hard part.

What the skill is not

The Ota skill is not a live MCP server. Ota publishes MCP discovery metadata today, but it does not currently run a live MCP protocol endpoint. That distinction matters. Discovery metadata can help agents understand the intended integration surface, but it is not the same as a callable server.

The skill is also not a replacement for repo-specific instructions. A repository can still need an AGENTS.md, contributor guide, security policy, or team review rules. The Ota skill covers Ota-specific behavior: how to understand and preserve repo readiness contracts.

Finally, the skill is not a permission slip for broad mutation. If a repo does not declare a safe task, setup path, or writable area, the agent should not silently invent one.

A better default for agent work

The best agent workflows are usually the least theatrical. They make fewer bad guesses.

When an agent enters an Ota repo, the ideal sequence is simple:

Read the Ota skill so it understands the operating model.
Inspect ota.yaml as the repo readiness source of truth.
Run ota doctor or ota validate to understand the current state.
Use ota tasks to discover supported commands.
Use ota run <task> for declared execution.
Report readiness failures as contract or environment issues instead of guessing around them.

That sequence feels slower only if you compare it to blind guessing in the first minute. After that, it is usually faster because it cuts false starts, side quests, and "works on my machine" fixes that were never real.

That is the practical value. The agent gets the same operating model every time. It does not need to rediscover Ota in each repo, and it does not need to guess whether ota.yaml is advisory or authoritative.

Why this matters for teams

Teams do not need more demos. They need agents that can enter a real repository and not immediately lower the trust level.

That means respecting setup, CI, local services, generated files, ownership boundaries, and verification paths. It means being able to say, "this repo is not ready yet," instead of pretending a broken environment is a code problem. It means treating repo readiness as infrastructure, not as a suggestion buried in prose.

The Ota skill is one piece of that system, but it is an important one. It gives the agent Ota-specific context before the first command runs. ota.yaml gives the repo its contract. The CLI gives humans, CI, and agents the same command surface.

That combination is the point.

If a team wants agents to be useful in production repos, the answer is not more vibe-based automation. The answer is stricter contracts, narrower boundaries, and tools that teach the agent what those boundaries actually mean.

That is why we built the Ota skill.

Originally posted here: https://ota.run/blog/the-ota-skill-for-ai-agents

Stop Asking AI Agents to Guess How Your Repo Works

Bobai Kato — Sun, 24 May 2026 00:00:00 +0000

AI coding agents are getting better, but a lot of repos still make them start from guesswork.

They land in a codebase and have to infer:

which command installs dependencies
which command starts the app
which services need to be running
which env vars matter
which workflow is safe to run
whether the repo is actually ready
what “done” should look like after a change

That is a lot of operational knowledge to hide in scattered README sections, old shell scripts, CI files, tribal memory, and half-working local setup notes.

And when an agent guesses wrong, the problem is not always the agent.

Sometimes the repo never gave it a reliable answer.

AI Agents Amplify Repo Readiness

A human contributor can pause, read docs, ask questions, remember past setup quirks, and work around drift.

An AI agent usually does something else: it follows the strongest signal it can find.

If your README says one thing, your CI says another, your package scripts say a third, and your local setup depends on an undocumented service, the agent has to choose. Sometimes it chooses well. Sometimes it burns time. Sometimes it changes the wrong thing because the repo never made the safe path explicit.

That is why repo readiness matters.

Before asking an AI agent to work in a repo, the repo should be able to answer basic questions clearly:

What does this repo need?
How does it become ready?
What tasks are safe to run?
What checks prove the repo still works?
What paths should an agent avoid?
What workflow should be used for this kind of change?

If those answers are not explicit, every agent has to rediscover them from scratch.

README Instructions Are Not Enough

READMEs are useful for humans, but they are not enough as the only source of operational truth.

A README can explain intent, context, and contribution style. But repo readiness needs something more precise:

declared runtimes
declared tools
declared services
declared tasks
declared workflows
declared checks
declared agent boundaries

That information should be machine-readable.

Not because humans do not matter, but because humans, CI, and agents should not each maintain separate versions of the same setup logic.

When setup knowledge only exists as prose, it drifts. When it drifts, automation becomes fragile. When automation becomes fragile, agents become less trustworthy.

The Repo Should Tell The Agent What Ready Means

A good agent workflow should not begin with:

“Look around and figure out how this repo works.”

It should begin with:

“Here is the repo contract. Diagnose readiness first. Use the declared workflow. Run the safe task. Respect protected paths.”

That is the difference between guessing and operating.

This is the layer I care about with Ota.

Ota gives a repo one explicit readiness contract: ota.yaml.

That contract can declare the repo’s tasks, checks, services, workflows, toolchains, env requirements, and agent-safe boundaries. Then humans, CI, and AI agents can all use the same source of truth.

For example:

ota doctor
ota workflows
ota tasks --workflow app
ota up --workflow app
ota run test

The point is not to replace good documentation.

The point is to stop making documentation carry operational truth alone.

What Agents Need From A Repo

An AI agent does not need magic. It needs clear boundaries.

A solid repo should be able to say:

agent:
  entrypoint: test
  default_task: test
  safe_tasks:
    - test
    - lint
    - typecheck
  protected_paths:
    - .env
    - secrets/**
    - production/**

The agent boundary tells agents which task to start from, which tasks are safe, and which paths are protected. The instruction is simple: run ota doctor first, then use declared safe tasks instead of guessing from repo scripts.

It should also be able to say what ready means:

workflows:
  default: app
  app:
    setup:
      task: setup
    run:
      task: dev
    readiness:
      checks:
        - app-ready

Now the agent is not guessing from random scripts.

It has a contract.

It knows the default workflow. It knows the safe tasks. It knows what not to touch. It knows which checks matter.

That is a better starting point for any coding agent.

CI Should Prove The Same Truth

Repo readiness should not only help local agents. It should also show up in CI.

If a repo has an explicit readiness contract, CI can prove that contract across environments:

name: ota-readiness

on:
  pull_request:
  push:

jobs:
  readiness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ota-run/setup@v1
      - run: ota doctor
      - run: ota validate .
      - run: ota up

That gives maintainers something concrete.

Not “the agent says it worked.”

A repeatable readiness check.

Why This Matters Now

AI agents are moving from demos into real repos.

That changes the bar.

A repo that is “understandable if you already know it” is not enough. A repo that “usually works after reading three docs pages” is not enough. A repo that depends on one maintainer’s memory is not enough.

If we want agents to make useful changes safely, repos need to become easier to reason about.

That means:

fewer hidden setup steps
fewer undocumented services
fewer ambiguous commands
fewer unsafe default paths
more explicit readiness
more machine-readable operational truth

The better your repo contract, the better every agent run becomes.

Get Started With Ota

Install Ota:

curl -fsSL https://dist.ota.run/install.sh | sh

Windows:

irm https://dist.ota.run/install.ps1 | iex

Then start with:

ota doctor
ota init --bootstrap
ota validate .
ota workflows
ota tasks

Useful links:

Install Ota: ota.run/docs/install
Ota docs: ota.run/docs
Ota source code: github.com/ota-run/ota
Example contracts: github.com/ota-run/examples
GitHub Action: github.com/ota-run/action
GitHub setup action: github.com/ota-run/setup

If your repo already has setup scripts, CI workflows, and contributor docs, Ota does not replace them blindly.

It helps turn the important parts into an explicit contract that humans, CI, and agents can all share.

Final Thought

AI agents should not have to reverse-engineer your repo every time they enter it.

Make the repo ready first.

Then let the agent work.

--
Originally Posted here: https://ota.run/blog/stop-asking-ai-agents-to-guess-how-your-repo-works-2olh

Pressure-testing Ota on Supabase: from setup prose to executable repo readiness

Bobai Kato — Sat, 23 May 2026 00:00:00 +0000

Supabase already has strong contributor documentation.

That is not faint praise. The docs are good. But good docs and executable readiness are not the same thing.

Before Ota, the www/docs contributor path still depended on a familiar manual loop:

read the docs
infer which workflow is the intended front door
install the right runtime and package manager versions
guess which commands are safe to run
decide whether the repo is actually ready, or only partially set up
if something fails on macOS, Windows, or Linux, figure out whether the problem is the repo, the machine, CI, or your shell

That is a normal setup experience in modern repos. It is also exactly where drift starts.

This post is about what changed when I added Ota to a scoped slice of the Supabase monorepo, how that improved the repo surface itself, and what the deeper pressure test exposed in Ota core.

Why this matters

Most repos still answer “why does this not run?” badly.

The failure mode usually looks like this:

local setup works differently from CI
one workflow is implied, but not explicitly declared
README setup and repo reality slowly diverge
native and container paths are present, but not clearly separated
readiness is inferred from “it seems to work” instead of declared checks
contributors and agents have to reverse-engineer what the repo expects

That is painful for humans. It is worse for agents.

If an AI agent is dropped into an unfamiliar repo, the first problem is usually not the code change itself. The first problem is operational ambiguity:

what this repo slice needs
which workflow is the front door
which tasks are safe
what “ready” means
what is actually blocking progress
what the next safe action should be

If the repo cannot expose that clearly, the agent is forced to guess from README prose, scripts, lockfiles, CI output, and convention.

That is what Ota is designed to remove.

What Ota added to Supabase

The upstream PR is intentionally scoped and intentionally lean:

PR: supabase/supabase#46269
Contract: ota.yaml

The PR adds:

an ota.yaml contract for the www/docs slice
a cross-OS contract matrix
Ota local artifact ignores
a small optional Ota section in CONTRIBUTING.md

That gives Supabase a machine-readable contract for:

the runtime and toolchain it expects
the workflows contributors should use
the setup tasks that make those workflows runnable
the readiness checks that prove the slice is actually up
the tasks and topology surfaces tooling can inspect directly

This is the shift from setup prose to executable repo readiness.

Before and after

Before Ota

The www/docs path was documented, but it was not encoded as repo truth.

That left both contributors and agents to reconstruct:

which commands matter
which runtime/toolchain versions are expected
whether native and container paths are meant to be equivalent
what should count as “ready”
how to distinguish a local issue from a repo contract issue

After Ota

That same slice can now answer those questions directly.

You can ask the repo:

ota validate .
ota doctor --workflow instant --native .
ota up --workflow instant --native --dry-run .
ota tasks --workflow app .
ota execution topology --json .

And the repo can answer from declared contract truth, not inferred setup lore.

For Supabase, that reduces four kinds of drift:

README drift

Setup prose can go stale. A contract is executable and testable.
Local vs CI drift

The same declared workflow can be pressure-tested in matrix CI.
Human vs agent drift

Humans and agents can consume the same operational truth surface.
Platform drift

Windows, macOS, and Linux differences get surfaced earlier instead of being rediscovered ad hoc.

Why the upstream PR stayed lean

This part was deliberate.

The public PR models the www/docs slice. It does not claim full Supabase readiness.

That is not a limitation of ambition. It is a review strategy.

A smaller honest contract is easier to review, easier to approve, and easier to trust than a broad fuzzy one. So the public change stays disciplined:

scoped slice
clear workflow surface
concrete CI pressure around that surface

But that did not mean I only did the minimum.

In parallel, I ran a deeper pressure test on a separate branch:

Supabase pressure branch

That separation mattered:

keep the upstream PR lean for higher approval odds
do the heavier product hardening outside the PR
fix real Ota gaps in Ota itself instead of hiding them in repo-local glue

That is the right way to use a serious repo as a product test surface.

The pressure test

The first PR branch was only the start.

The full pressure cycle expanded into:

native matrix coverage across Ubuntu, macOS, Windows PowerShell, and Windows Git Bash
container matrix coverage across supported runner surfaces
strict E2E parity checks
bounded verification tasks
a broader studio slice on the pressure branch
repeated reruns to separate repo noise from real Ota defects

Representative runs:

Lean PR branch matrix: run #26281955993
Full pressure branch green run: run #26300846166

This is where the value of Ota becomes clearer.

The point was not just to prove that ota.yaml could validate.

The point was to prove that the readiness model, workflow targeting, and platform behavior held up under real pressure.

What the contract actually models

At a high level, the contract models:

Node + pnpm toolchain expectations
native and container execution surfaces
workflow-specific setup paths
HTTP readiness for www and docs
safe bounded tasks for validation and verification

That gives the repo a surface that tools can inspect directly instead of inferring from scattered files.

For example:

ota validate .
ota doctor --workflow instant --native .
ota up --workflow instant --native --dry-run .
ota tasks --workflow app .
ota execution topology --json .

Those commands are not wrappers around documentation. They operate from declared repo truth.

What actually broke in Ota

Supabase exposed a real Ota bug.

The problem was selected workflow toolchain scoping.

In practice, Ota could let unrelated toolchain-owned tools leak into a selected workflow surface just because they were declared elsewhere in the contract.

That sounds small. It is not.

If a selected workflow does not require something, Ota should not silently activate or diagnose against it just because the broader repo declares it somewhere else.

If it does, you get:

noisy dry-runs
misleading readiness signals
false activation pressure
lower trust in workflow targeting

That bug was not fixed in the Supabase contract.

It was fixed in Ota core.

That distinction matters. If the platform is wrong, the correct move is to fix the platform, not teach users to work around it.

What did not count as an Ota bug

The pressure test also surfaced failures that looked suspicious at first but were not Ota defects.

The clearest example was the Docker-backed Studio path on hosted CI.

That failure came from runner and stack-specific behavior in the Supabase Docker environment, including hosted ulimit constraints. That is real repo/runtime behavior, but it is not an Ota orchestration bug.

So the right response was:

do not misclassify repo or runner behavior as an Ota platform defect
do not hide runtime limitations just to force more green boxes
keep the matrix useful for signal, not vanity

Trust is not built by making every box green. Trust is built by classifying failures correctly.

What value this adds to Supabase

The value here is not “Supabase now has another YAML file.”

The value is that a real slice of the repo now has:

an explicit operational contract
declared workflow entry points
repeatable readiness checks
machine-readable task and topology surfaces
cross-platform pressure testing around that declared truth

For Supabase maintainers, that means:

less rediscovery of the same setup blockers
earlier visibility into platform-specific drift
a clearer operational model for contributors

For contributors, that means:

less guessing
less README archaeology
less ambiguity around which path is actually supported

For agents, that means:

fewer blind setup guesses
a clearer answer to “what should I run?”
a more reliable signal for “is this repo ready, or am I about to make changes in a broken environment?”

Why Ota still adds value when a repo already has good docs

A fair question is: if Supabase already has solid docs, what does Ota add?

Docs and contracts do different jobs.

Docs explain.

Contracts declare.

Docs are excellent for onboarding context, caveats, workflow explanation, and human guidance. But docs do not usually answer machine-checkable questions like:

is this workflow ready right now?
which workflow is the front door?
which setup path belongs to this slice?
which checks prove readiness?
which tasks are safe for agents?
how does this differ across native and container execution?

That is the gap Ota fills.

It does not replace good docs. It gives the repo an executable readiness layer that docs alone cannot provide.

Why this matters beyond Supabase

The Supabase case study is really about a broader repo question:

What should happen when a repo does not run?

Most repos still answer that question badly.

They fail, and then they force the contributor to become the diagnosis layer.

Ota changes that shape.

A repo can declare:

what it needs
how it becomes runnable
what ready means
what is safe to run
what should block progress

That turns readiness from tribal knowledge into contract truth.

Supabase is a useful example because it is large enough to expose real pressure, but still scoped enough to model honestly.

Current state of the PR

The upstream PR is intact:

supabase/supabase#46269

From our side:

no unresolved actionable review threads
contract and matrix changes are clean
remaining red checks are upstream Vercel authorization and deploy noise, not Ota contract failures

So the Ota side of the work is sound.

Try it on your repo

If your repo already has setup docs, that is a good start.

The harder question is whether the repo can expose, in a machine-readable and testable way:

what it needs
how it becomes runnable
what ready means
what is safe to run
what should block progress

That is where Ota adds value.

If you want to pressure-test that on a real codebase, start here:

ota-run/ota

And if you want to start from the Supabase example specifically:

Note: at the time of writing, the upstream Supabase PR is still open. I’ll update this post with the final outcome once maintainers finish review.

References

The concrete artifacts from this work are here:

Originally post on Ota Blog: https://ota.run/blog/pressure-testing-ota-on-supabase-from-setup-prose-to-executable-repo-readiness-1ion

Pressure Testing Ota on n8n: A Closed PR That Still Proved the Point

Bobai Kato — Tue, 19 May 2026 13:54:52 +0000

I ran a real pressure test on one of the most visible OSS automation repos: n8n-io/n8n.

PR: n8n-io/n8n#30714

At first glance, a closed PR looks like a loss. It wasn’t.

Why this test mattered

n8n is a high-signal repo for readiness tooling:

large monorepo
multiple contributor paths
cross-platform contributors
native + Docker runtime surfaces
mature existing docs

If Ota only works on simple repos, it’s not infrastructure.

n8n is exactly the kind of repo that exposes whether Ota is real.

Before vs After (in the test branch)

Dimension	Before	After (Ota branch)
Readiness definition	Documented across markdown instructions	Explicit contract in `ota.yaml`
Cross-OS proof	Implicit, contributor-dependent	Matrix proof in GitHub Actions
Workflow entrypoints	Manual command selection	Named workflows (`app`, `backend`, `instant`, `docker`)
Machine-checkable status	Partial	Deterministic `ota proof` outcomes
Agent bootstrap metadata	None	`agent.bootstrap.ota` declared

This was additive. It did not replace n8n’s canonical setup flow.

What was added

In my branch I introduced:

ota.yaml with workflow-specific readiness paths
a smoke matrix workflow for Linux/macOS/Windows + Docker proof
pinned Ota version in CI for deterministic behavior
optional contributor-facing Ota guidance

Green proof run example:

Run 26092939099

Why maintainers closed it

The maintainers closed the PR (n8n-io/n8n#30714) for policy reasons, not technical failure:

they don’t currently need an extra readiness layer
they keep CI third-party dependencies narrow
they don’t want contributor docs to endorse an external tool

That’s a valid maintainer call.

The actual value

Even without merge, this test delivered high-value evidence:

Ota can model and prove readiness on a complex repo.
Cross-platform behavior held under matrix pressure.
Adoption boundaries are now clearer: technical fit and governance fit are separate gates.
Ota got sharper through real-world constraints, not synthetic demos.

So this is demonstrated value, not adopted value.

Final take

A closed PR can still be a product win.

This n8n test proved Ota’s technical posture under real load, clarified adoption constraints, and generated stronger evidence for the next integration target.

That’s exactly what pressure testing is for.

Get Started with Ota

Ready to pressure-test your own repo? Start here:

Install Ota: ota.run/docs/install
Ota docs: ota.run/docs
Ota GitHub: github.com/ota-run/ota
Contract examples: github.com/ota-run/examples

First commands (safe for any repo)

ota doctor
ota workflows
ota tasks --use
ota validate .

Prove a workflow (replace with one from `ota workflows`)

ota proof --workflow <workflow-name>

If your repo has no contract yet

ota init --bootstrap
ota validate .

Use the examples repo as a base, then define workflow names that match your repo.

--
Originally posted here: https://ota.run/blog/pressure-testing-ota-on-n8n-a-closed-pr-that-still-proved-the-point-1jf3

DEV Community: Bobai Kato

Why Developer Onboarding Should Be Contract-First

Overview

Why Developer Onboarding Still Breaks

What “Contract-First” Actually Means

Why README-First Onboarding Breaks Down

A Repo-Shaped Onboarding Failure

Why Ota Is The Right Layer

The Practical Difference

Why This Matters More With AI Agents

Closing

Pressure-testing Ota on Discourse: repo-wrapper truth matters more than a passing bundle command

Overview

Before Ota

The mistake that mattered

What Ota had to learn

The final contract shape

What the matrix now proves

Why this repo is worth writing about

Links:

Ota vs Dev Containers

Overview

What Dev Containers Are Actually Good At

What Dev Containers Do Not Solve

What Ota Solves Instead

The Wrong Comparison

Why This Matters For AI Agents

Concrete Example

What Ota Adds On Top Of Dev Containers

When Dev Containers Are Enough

So, Ota or Dev Containers?

Closing

Pressure-testing Ota on Osiris: making runtime proof and Docker paths honest

Overview

Before Ota

What we modeled

What Osiris exposed in Ota

1. Detached native external-state starters were misclassified

2. Runtime proof treated warning-only doctor reports as failure

What changed

What the matrix now proves

Why this matters

Links:

Pressure-testing Ota on OpenHands: from setup fragmentation to execution governance

Overview

Why OpenHands was a strong test

Where the repo actually fought back

What changed

Links:

The contract decisions that mattered

Before and after

Before:

After:

Why the matrix had to be opinionated

Why:

Takeaway

Get Started with Ota

The Ota Skill for AI Agents

Overview

Why an Ota skill exists

What the skill teaches an agent

The contract still comes first

Installing the skill

What the skill is not

A better default for agent work

Why this matters for teams

Stop Asking AI Agents to Guess How Your Repo Works

AI Agents Amplify Repo Readiness

README Instructions Are Not Enough

The Repo Should Tell The Agent What Ready Means

What Agents Need From A Repo

CI Should Prove The Same Truth

Why This Matters Now

Get Started With Ota

Final Thought

Pressure-testing Ota on Supabase: from setup prose to executable repo readiness

Why this matters

What Ota added to Supabase

Before and after

Before Ota

Prove a workflow (replace with one from `ota workflows`)