DEV Community: Ota

Your Documentation Isn't the Problem. Your Governance Is.

Adamma — Sun, 21 Jun 2026 16:57:48 +0000

Most teams think repository failures come from weak documentation.

Usually, they do not.

The README exists.

There is an onboarding guide.

There is an AGENTS.md file.

There may even be a detailed CI workflow proving the clean path.

And yet contributors still get stuck, local setup still drifts, agents still guess, and CI still catches things nobody ran locally.

That is not mainly a documentation failure.

It is a governance failure.

The repo explained itself.

It did not govern execution clearly enough.

That distinction matters a lot more now that repos are operated by humans, CI systems, remote sandboxes, and AI agents.

Documentation can explain what should happen.

A governed repo can declare what is required, what is safe, what is protected, what must be verified, and when execution should stop.

That is the category Ota is built for.

The simplest version is:

Documentation can describe a rule.

Governance decides whether the repo actually operates by it.

Good Documentation Still Leaves The Hard Part Open

Documentation is useful.

A good README gives context.

A contributor guide explains conventions.

An AGENTS.md file helps an AI agent understand how to behave in a repo.

None of that is the problem.

The problem is asking documentation to carry execution truth by itself.

A README can say:

Run setup before tests.

An AGENTS.md file can say:

Do not touch deployment config.

A contributor guide can say:

Run the full verification path before opening a pull request.

Those may all be correct.

But the repo still has unresolved operational questions:

what exactly counts as setup
which test path is the real one
whether the verification path is one command or several
whether setup is safe for unattended automation
which files are protected
what should stop an agent instead of letting it guess

That is why documentation and governance are different layers.

Documentation explains.

Governance defines the operating boundary.

A Small Failure Pattern

Imagine a repo where:

the README says npm test
CI runs pnpm lint, pnpm typecheck, and pnpm test:ci
Redis must be running before integration tests pass
.env.local should never be edited automatically

Nothing here is mysterious.

Everything is documented somewhere.

And the repo still fails the moment a new contributor or an AI agent tries to operate from the wrong authority.

The command in the README passes a partial check.

CI still fails.

The agent starts debugging application code.

The real problem was missing service readiness and an incomplete verification path.

That is the issue.

The repo had information.

It did not have one clear operational authority.

The Problem AI Agents Are Exposing Already Existed

AI agents did not create this weakness.

They are exposing it faster.

Human teams often survive weak repo governance through social recovery:

ask a teammate
remember the unofficial setup order
notice that a command "looks wrong"
learn which files nobody edits casually

Agents do not have that recovery layer.

They operate from what the repo declares.

If the repo leaves important execution truth scattered across README prose, package scripts, workflow files, shell history, and maintainer memory, the agent is forced to infer the missing parts.

And inference is not governance.

That is why "just add better instructions" is usually the wrong answer.

The harder problem is not explanation quality.

It is whether the repo has one explicit operational contract.

The Real Gap Is Not Knowledge. It Is Operational Authority.

Most repos already contain the knowledge somewhere.

The issue is that they do not give that knowledge one clear authority surface.

That creates familiar failure patterns:

the README and CI disagree about the real verification path
a service dependency is treated like a code failure
a maintainer-only helper command looks like a normal recovery path
local protected state gets dragged into automation by accident

Nothing here is undocumented in the broad sense.

Everything exists somewhere.

But the repo still fails because nobody can answer, from one place:

what the canonical setup path is
what the canonical verification path is
which tasks are safe for agents
which paths are protected
whether a missing service is a blocker or a code failure

That is the governance gap.

The repo has information.

It does not yet have operational authority.

What Ota Changes

Ota does not try to replace documentation.

It gives the repo a contract for execution governance.

That contract lives in ota.yaml.

It can declare:

the required toolchains and package managers
the setup path
the declared tasks
the canonical workflow
the verification path
the agent-safe task surface
the writable and protected boundaries
the conditions that should stop execution

That is a different category from prose.

Instead of asking humans and agents to reconstruct the repo from scattered clues, the repo can expose one reviewable source of operational truth.

For example:

version: 1
project:
  name: example-app

toolchains:
  node:
    version: "22"
    package_managers:
      pnpm: "10.0.0"
    fulfillment:
      source: corepack
      mode: run

tasks:
  setup:
    prepare:
      kind: dependency_hydration
      medium: package_dependencies
      source:
        kind: node_package_manager
        cwd: .
        manager: pnpm
        mode: install
        frozen_lockfile: true
    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

  test:
    depends_on:
      - setup
    command:
      exe: pnpm
      args:
        - test:ci
    requirements:
      toolchains:
        - node

agent:
  entrypoint: setup
  default_task: test
  safe_tasks:
    - build
    - test
  verify_after_changes:
    - test
  writable_paths:
    - src
    - tests
  protected_paths:
    - ota.yaml
    - .env.local
    - infra/production

That contract does not just describe the repo.

It gives the repo a governed surface:

setup is declared instead of implied
test is declared instead of guessed from scripts
build and test are explicit safe lanes for agents
.env.local and production infra are explicit boundaries

That is much stronger than "the README mentioned it."

Governance Needs Commands, Not Just Claims

The contract matters because Ota can operate from it directly.

That is where the difference becomes practical.

The repo can use:

ota doctor
ota validate
ota tasks --safe --use
ota up --dry-run
ota run test

Each command answers a different governance question:

ota doctor: is the repo actually ready, and what is the first blocker
ota validate: is the contract itself structurally and semantically sound
ota tasks --safe --use: what can an agent run safely from the declared task surface
ota up --dry-run: what setup path is about to be executed before any mutation starts
ota run <task>: run the named task through the contract instead of guessing from scripts

That is what stronger repo governance looks like.

not more prose, but a contract plus commands that can use it.

This Is Governance, Not Magic Enforcement

It is important to be precise here.

Ota is not pretending to be a universal hard-lock runtime for every possible repo action.

That would be a vague claim and a weak product story.

The stronger and truer claim is this:

Ota gives the repo a governed contract surface for readiness, setup, execution, verification, and agent boundaries.

It makes important operational rules explicit, reviewable, diagnosable, and runnable through one shared layer.

That is already a major step up from:

README-only setup
CI-only truth
script-only conventions
instruction-only agent guidance

In other words:

documentation explains
contracts govern
proof validates

That is a much more accurate frame for Ota than treating it as "just docs" or overstating it as total enforcement of every environment.

The Repos That Scale Best Remove Guesswork

The repositories that work best for humans and agents are not usually the ones with the most words.

They are the ones with the least ambiguity.

You know:

what the repo needs
how it becomes ready
which tasks are safe
what counts as verification
what should stop progress
what should not be touched casually

That is the real scaling property:

not explanation volume,

but operational clarity.

That is why the next maturity move for modern repos is not simply "improve the docs."

It is:

move the important execution rules into a contract the repo can actually operate from.

Conclusion

Documentation is not the enemy.

Weak governance is.

Most repos already have plenty of explanation.

What they lack is one explicit authority surface for how execution works.

That is the gap Ota is built to close.

Not by replacing README files or AGENTS.md.

By giving the repo a contract that can declare what is required, what is safe, what is protected, what is verified, and when execution should stop.

That is the shift that matters.

From explanation to operational authority.

From instructions to governance.

Explore the Ota getting started guide
Check out the Ota examples repo

Originally posted @ ota.run

Software Execution Governance Starts Before Production

Adamma — Tue, 16 Jun 2026 21:14:09 +0000

Most teams still talk about governance as if it begins at deployment.

Approvals. Production access. Compliance review. Audit trails.

All of that matters.

But by the time software reaches production, many of the most important execution decisions have already happened:

dependencies were installed
scripts were executed
services were started
environments were configured
secrets were required
agents were allowed to act

That is why I think the usual framing is incomplete.

Software execution governance starts before production. It starts the moment someone runs a repository.

The Gap Most Teams Still Ignore

Most organizations govern production carefully while leaving repository execution loosely managed.

A contributor clones a repo, reads the README, and runs whatever setup path seems right.

Maybe it works.

Maybe it expects undocumented services.

Maybe it mutates local state.

Maybe it reaches external systems.

Maybe it asks an AI agent to infer what is safe.

Execution is already happening. The governance layer is just missing.

That is the gap.

Risk Does Not Start At Deployment

A repository can do a lot before any deployment exists:

install software
run scripts
modify files
start infrastructure
request credentials
bind ports
touch Docker, databases, or cloud tools

None of that makes repositories “bad.”

It just means execution has consequences much earlier than most governance models admit.

The operator can be:

a developer
a CI runner
an automation system
an AI agent

The operator changes.

The execution risk does not.

Why AI Makes This Impossible To Ignore

For years, teams got away with weak repository governance because humans could fill in the missing pieces.

Someone knew:

which command actually mattered
which service needed to be running first
which script was outdated
which path was safe
what “done” really meant

AI agents do not have access to that hidden context unless the repository declares it.

That is why AI is exposing a problem that already existed.

The issue is not that agents are inherently reckless.

The issue is that many repositories still depend on tribal knowledge at the exact point where execution begins.

Inference is not governance.

One Real Repo-Shaped Problem

Pressure-testing real repositories makes this obvious fast.

Take a repo like n8n.

It has multiple legitimate execution paths:

a contributor path through the monorepo
a quickstart path through npx n8n
a container path through Docker

All three are real.

But they do not share the same prerequisites, the same setup path, or the same readiness meaning.

If that truth is only spread across README prose, scripts, CI workflows, and maintainer memory, the repo is already under-governed before production is even relevant.

That is the problem Ota is trying to solve.

Governance Means Declaring Intent

Good governance is not bureaucracy.

It is ambiguity reduction.

A governed repository should be able to answer:

what this repo requires
which workflow is the intended front door
what must happen before work can run
which services matter
what “ready” means
which tasks are safe
which paths are protected
what verification is required
when execution should stop

Those are execution questions.

And they show up before deployment.

What Ota Makes Explicit

One of the core ideas behind Ota is simple:

the repository should be able to explain how it operates without requiring a maintainer to translate it every time.

That means the repo can declare things like:

What it needs
What can run
What should run
What should not run
What requires approval
What verification means
When execution should stop

And more importantly, Ota can make those answers executable through one contract.

A compact shape looks like this:

yaml|OTA Contract
version: 1
project:
  name: app-service
  type: application
toolchains:
  node:
    version: "22"
    package_managers:
      pnpm: "10.0.0"
tasks:
  setup:
    prepare:
      kind: dependency_hydration
      medium: package_dependencies
      source:
        kind: node_package_manager
        cwd: .
        manager: pnpm
        mode: install
        frozen_lockfile: true
    requirements:
      toolchains:
        - node
    safe_for_agent: true
  test:
    command:
      exe: npm
      args:
        - test
    depends_on:
      - setup
    requirements:
      toolchains:
        - node
    safe_for_agent: true
  deploy:
    command:
      exe: npm
      args:
        - run
        - deploy
    depends_on:
      - setup
    requirements:
      toolchains:
        - node
workflows:
  default: contributor
  contributor:
    setup:
      task: setup
    run:
      task: test
agent:
  entrypoint: setup
  default_task: test
  safe_tasks:
    - setup
    - test
  protected_paths:
    - ota.yaml
    - .env.production
  verify_after_changes:
    - test

That is not just command exposure.

That is execution governance:

one declared front door
one declared verification path
one agent-safe boundary
one explicit approval boundary for higher-risk execution
one explicit protected-path surface

The Command Layer Matters Too

Once the contract exists, the repo can expose a more trustworthy execution path for humans and agents:

ota validate
ota doctor
ota up
ota run verify

Those commands answer different questions:

ota validate checks whether the contract itself is sound
ota doctor explains what is blocked right now
ota up prepares the repo along the declared path
ota run verify executes the canonical verification task

That is a stronger operating model than “read the README, inspect the scripts, and hope you found the real path.”

This Is Becoming A Repository Concern

As AI-assisted development becomes normal, more repos will be executed by automation and agents before a human ever asks a maintainer what the right command is.

That means governance can no longer remain a production-only concept.

Repositories need:

declared operating rules
verification boundaries
machine-readable execution contracts
one source of execution truth

In other words, they need software execution governance at the repository boundary itself.

Conclusion

The old model says governance begins when software reaches production.

That is too late.

Execution begins much earlier:

when a repository is cloned
when setup starts
when services are launched
when CI runs
when an AI agent begins work

That is where trust begins.

That is where assumptions become actions.

And that is where governance belongs.

Because software execution governance does not start in production.

It starts the moment execution begins.

Explore the Ota getting started guide
Check out the Ota examples repo

Originally posted @ ota.run

Ota v1.6.20 Now Available

Adamma — Sat, 13 Jun 2026 17:27:48 +0000

v1.6.20 is a contract-governance release.

As Ota has moved from repo readiness into broader software execution governance, the trust problem has shifted.

It is no longer enough for Ota to execute a repository successfully once.

The harder requirement is that every public execution surface stays trustworthy:

published contract schemas
doctor findings consumed by automation
workflow-owned environment truth
service topology and readiness ownership
dependency preparation and orchestration behavior
If those surfaces drift, Ota starts to look correct while becoming less dependable.

That is exactly the kind of failure execution governance is supposed to prevent.

So the goal for v1.6.20 was direct: make more execution truth explicit, machine-readable, versioned, and release-governed.

Feature

v1.6.20 ships a broad but coherent set of governance improvements. The main story is not “more YAML.” The story is that more of the repo’s actual operating model can now be published, validated, and trusted.

1. Contract publication became a governed release surface

Repo and workspace contract schemas are now treated as real public APIs.

That means:

published repo and workspace schemas are generated from the Rust-owned source of truth
release and compatibility checks now fail on schema drift
shipped examples and canonical contract docs validate against those published schemas
contract publication is no longer a best-effort artifact

This is a meaningful step for humans, CI systems, editors, and AI agents. Once contracts are public machine-readable surfaces, they need the same release discipline as any other API.

2. Doctor output became more stable for machine consumers

ota doctor --json now carries stronger governed identity across findings.

Instead of forcing downstream tooling to infer meaning from rendered summary text, Ota now preserves stable finding identity more consistently across:

doctor findings
policy-backed findings
workflow and service findings
env and provisioning findings
ota explain --json
workspace doctor/check surfaces

That means integrations can depend more on structured codes, categories, ownership, and blocker metadata, and less on brittle summary parsing.

3. Environment ownership became first-class

This release significantly expands what Ota can own around environments.

v1.6.20 adds or strengthens:

env.profiles
workflow-level env profile selection
workflow-owned rendered dotenv artifacts
richer ensure_env_file behavior
first-class checks[].kind: env
allowed host and URL-host assertions
env-file overlays on task execution paths

The important shift is architectural: environment truth no longer has to be spread across shell snippets, copy commands, grep-based checks, and task-local duplication. More of that logic can now live in the contract itself.

4. Services and topology got more truthful

Service modeling also moved closer to how real systems actually work.

v1.6.20 improves:

canonical Compose manager modeling
structured compose_health readiness
multi-endpoint service identity
endpoint-specific context ownership
endpoint-aware readiness and env bindings
host-published Compose port detection

This matters because real repos rarely have just one flat “service URL.” They have host projections, multiple endpoints, readiness ownership, and task/service relationships that need to be modeled honestly.

5. Workflow, setup, and dependency preparation got stronger

The workflow and setup path is now much more expressive without falling back to shell glue.

This release adds or expands:

workflow-native prepare.task for finite setup work
first-class dependency hydration for package and image setup
aggregate tasks as structured entrypoints
stronger env-file and setup ownership at the workflow level

That gives contracts a better way to say:

what must happen before the main workflow
which setup work is finite and structural
which verification path is canonical
how shared preparation should be modeled without fake parent tasks

6. Ota now owns more of the execution layer itself

v1.6.20 also widens execution governance into orchestration and ownership lanes that used to be much looser.

That includes:

first-class orchestrator modeling
Mise as the first supported orchestrator
stronger toolchain ownership, including Poetry under Python
better separation between runtime/tool/package-manager owners
better selected-path execution truth for env artifacts and requirement projection

This is one of the more important long-term shifts in the release. Ota is becoming less dependent on opaque shell mediation and more capable of governing the execution layer directly.

One concrete example

Before this release, a repo could still end up with execution truth split across several places:

contract examples in docs
generated schemas
Rust contract types
doctor JSON
workflow-owned env behavior Each individual surface might look fine, but if they drifted from each other, machine consumers would get an unreliable picture of the repo.

v1.6.20 closes a lot of that gap.

For example, a workflow can now own environment profile selection and rendered dotenv artifacts directly, while the published contract schema, validation path, execution reporting, and proof JSON all stay aligned to that same declared model.

That is the difference between a feature existing and a feature being governable.

Taken together, these changes do not just add capabilities.

They make more of Ota’s behavior publishable, enforceable, and trustworthy as execution truth.

Docs

If you want to adopt these capabilities directly, use the live docs:

Get Started: Install Ota and run ota doctor in your repository.
Contract Reference: Repo contracts, workspace contracts, services, environments, workflows, orchestration, and toolchains.
Command Reference: ota doctor, ota env, ota run, ota up, ota proof, and related execution commands.
Environment Modeling: Environment profiles, dotenv rendering, environment checks, and ownership surfaces.
Service Modeling: Managed services, readiness, endpoint ownership, and topology definitions.

Release

v1.6.20 is live.

If you already use Ota, upgrade and verify:

ota --version
ota validate
ota doctor
ota env
ota run <task> --dry-run --json

If you are evaluating Ota for the first time, v1.6.20 is one of the clearest releases yet for understanding where the product is going.

Ota is not only trying to make repositories runnable.

It is building governed execution truth for humans, CI systems, automation, and AI agents, where contracts, diagnostics, environments, services, toolchains, and orchestration all become explicit parts of the same operating model.
Command reference: Commands for ota doctor, ota env, ota run, ota up, and ota proof
Workflow modeling: Workflows for canonical front doors, setup, prepare, and readiness
JSON output: JSON output reference for machine-readable execution and diagnosis surfaces
Release

v1.6.20 is live here: https://ota.run/releases/v1.6.20

If you already use Ota, upgrade and verify:

VERIFY
bash
Copy
ota upgrade
ota --version
ota validate
ota doctor
ota env
ota run --dry-run --json
If you are evaluating Ota for the first time, v1.6.20 is one of the clearest releases yet for understanding where the product is going.

Ota is not only trying to make repositories runnable.

Why Tribal Knowledge Breaks Repos for AI Agents

Adamma — Sat, 13 Jun 2026 14:22:09 +0000

Every repo has a little tribal knowledge.

The command everyone knows not to run.
The service that must be started before tests.
The environment variable missing from .env.example.
The setup step that only lives in someone’s memory.
The CI behavior nobody explains because "that’s just how this repo works."

For human teams, tribal knowledge is already expensive.

For AI-native repos, it is worse.

It is incompatible with the operating model.

An AI-native repo is not just a repo where someone occasionally uses an AI coding tool. It is a repo where humans, CI, automation, and AI agents are all expected to reason about the same codebase and take useful action from the same operating truth.

That model breaks if the repo’s real rules live outside the repo.

This is one of the clearest reasons Ota exists. Ota is built around software execution governance for humans and AI agents. A repo should not depend on memory, Slack history, or maintainer intuition to explain how execution works. It should declare what it needs, what can run, what is safe, what should be verified, and where agents must stop.

Tribal knowledge does the opposite.

It hides the rules.

Tribal Knowledge Was Never Harmless

Teams often treat tribal knowledge as normal.

Someone joins the repo and asks:

How do I run this locally?

A maintainer replies:

Oh, the README is outdated. Use pnpm now.

Or:

Run the migration first, but not the reset command.

Or:

The tests only pass if Redis is already running.

Or:

Ignore that script. CI does something different.

Humans can survive that kind of repo because they have a social recovery layer. They can ask follow-up questions. They can notice hesitation. They can ask whether something is safe.

AI agents do not have that layer.

They inspect files, choose commands, run checks, edit code, and report status.

If the real rule is not declared, the agent has to infer it.

And inference is not governance.

AI-Native Repos Need Declared Operating Truth

A repo becomes AI-native when agents are expected to do real work inside it.

That does not mean the agent owns the repo. It means the repo has to be legible to non-human operators.

A serious repo should be able to answer:

what runtime and tools are required
what setup path should run first
which workflows are canonical
which tasks are declared
which tasks are safe for agents
which paths are writable
which paths are protected
what counts as verification
which blockers require approval
what status automation should consume

Those answers cannot live only in someone’s head.

They should not be scattered across README prose, package scripts, CI files, shell history, and old issue comments either.

This is where Ota is useful.

Ota gives the repo one declared contract for that operating truth.

Instead of asking humans and agents to rediscover the rules every time, the repo can declare them in ota.yaml and expose them through a stable command surface.

Hidden Setup Turns Readiness Problems Into Debugging

One of the most common failures in AI-assisted development is not bad code.

It is hidden setup.

An agent runs a test, sees a failure, and tries to fix the application. But the real problem is that Postgres was not running. Or the wrong Python version was active. Or a required CLI was missing. Or the repo needed a bootstrap step that nobody declared clearly.

From the agent’s perspective, the failure is real.

From the repo’s perspective, the failure is misleading.

The repo was not ready for the task.

This is why hidden setup knowledge is dangerous. It converts readiness blockers into debugging sessions. Humans waste time. CI becomes noisy. Agents patch the wrong layer.

Ota’s position is simple: surface the blocker first.

Not:

Run the test and interpret the crash.

But:

This task requires Postgres.
Postgres is not available.
Stop here.

That is a better operating model.

That is what ota doctor is for.

A Simple Failure Pattern

This failure pattern shows up all the time:

the README says pnpm test
the real test path also needs Redis
nobody declared that clearly
the agent runs tests
the tests fail
the agent starts changing application code
the real problem was missing setup, not broken code

That is not an AI-quality issue.

That is a repo-truth issue.

In a governed repo, the sequence should be different:

ota validate
ota doctor
see that test requires Redis
stop at the blocker
prepare the repo correctly
only then run the declared task

That is the practical value of replacing tribal knowledge with contract truth.

Hidden Safety Rules Create Risky Execution

Tribal knowledge is not only about setup.

It is also about safety.

Every mature repo has commands that should not be run casually:

deploy
publish
db:reset
terraform apply
seed-production

It may also have files that should not be edited without review:

.env
lockfiles
migrations
generated files
production config
deployment scripts

A human maintainer may know these boundaries instinctively.

An AI agent needs them declared.

Telling an agent "be careful" is not enough. The repo should say what careful means.

Safe tasks should be explicit.
Writable paths should be explicit.
Protected paths should be explicit.
External-state mutation should require approval.

That is how Ota moves agent safety from advice into execution governance.

Hidden Verification Creates False Confidence

A repo can also hide what "done" means.

The README may say:

Run tests before opening a PR.

But the actual verification path might be:

lint
typecheck
unit tests
integration tests
build
migration check

If the agent only runs the visible test command, it may report success while CI still fails.

Humans do this too.

The deeper issue is that the repo has not declared the difference between a quick check and full verification.

In an AI-native repo, that distinction must be explicit.

Agents need finite, declared verification paths.
CI needs stable signals.
Humans need to know what evidence was actually produced.

That is why Ota gives the repo declared tasks, workflows, and verification surfaces instead of leaving "done" to interpretation.

What Ota Replaces

Ota replaces tribal knowledge with a contract.

In an Ota-backed repo, ota.yaml becomes the place where the repo declares:

runtimes and tools
setup requirements
workflows
declared tasks
safe tasks
verification tasks
writable paths
protected paths
agent entrypoints
execution boundaries

That changes the question from:

Who knows how this repo works?

to:

What has this repo declared about how it works?

That is the category shift.

Not better onboarding prose.

Declared execution truth.

What Ota Adds That README Prose And Scripts Cannot

README prose and helper scripts are useful.

They are not enough on their own.

They can explain or execute steps. They cannot, by themselves, give the repo a first-class execution contract.

Ota adds things that tribal knowledge, docs, and scripts do not naturally provide:

machine-readable readiness
ota doctor diagnosis before execution starts
ota validate contract validation
declared workflows instead of implied front doors
dry-run and preview behavior before mutation
safe-task boundaries for AI agents
protected-path boundaries for sensitive files and directories
one shared truth for humans, CI, and agents

That is the difference between repository guidance and repository governance.

What This Looks Like In Practice

A small Ota contract can already replace a surprising amount of tribal knowledge:

version: 1
project:
  name: app

runtimes:
  node: "22"

tools:
  pnpm: "10"

tasks:
  setup:
    run: pnpm install --frozen-lockfile

  build:
    depends_on:
      - setup
    run: pnpm build

  test:
    depends_on:
      - build
    run: pnpm test:ci

agent:
  entrypoint: setup
  default_task: test
  safe_tasks:
    - setup
    - build
    - test
  writable_paths:
    - src
    - tests
  protected_paths:
    - .env.local
    - infra/production
  verify_after_changes:
    - build
    - test

That contract tells humans and agents:

which runtime matters
which package manager matters
what setup means
what task should run next
what is safe
what should not be touched
how to verify changes

That is already much stronger than maintainer memory plus a stale README.

And then the repo gets an actual operating flow:

ota validate
ota doctor
ota up --dry-run
ota run test

That is the practical difference between guessing and governed execution.

A Repo Should Be Able To Speak For Itself

A repo that has moved beyond tribal knowledge can speak for itself.

It can say:

This repo needs Node 22 and pnpm 10.
Setup is declared here.
Build depends on setup.
Tests depend on build.
The safe agent tasks are setup, build, and test.
The agent may write to src and tests.
The agent must not edit .env or deployment config.
Full verification means build plus test.
If credentials are missing, stop and report the blocker.

That is not excessive process.

That is operational clarity.

It gives humans a faster path.
It gives CI a cleaner contract.
It gives agents boundaries.
It gives maintainers evidence.

Most importantly, it makes the repo less dependent on whoever happens to remember the rules.

The Hidden Rule Is The Broken Rule

A README can explain.
An AGENTS.md file can guide.
CI can enforce.
Maintainers can decide.

But the repo still needs a declared operating layer that all of them can share.

Tribal knowledge cannot provide that layer.

It is not reviewable.
It is not validated.
It is not machine-readable.
It is not stable enough for automation.
It does not give agents a safe boundary.

Ota does.

That is why this matters beyond onboarding. It is not just about helping the next developer get started faster. It is about making execution legible enough for AI agents and automation to participate without turning every action into a guessing game.

Conclusion

Tribal knowledge does not scale into AI-native development.

It may work when a small team can ask each other questions in real time. It does not work when humans, CI, automation, and AI agents all need the same repo to explain itself.

AI-native repos need more than instructions.

They need declared execution governance.

They need to say what is required, what is safe, what is verified, what is blocked, and what must stop.

That is the work Ota is built for.

Not making repos look documented.

Making repo execution governable.

Because in an AI-native repo, the hidden rule is the broken rule.

Explore the Ota getting started guide
Check out the Ota examples repo

Originally posted @ ota.run

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

Running an Unfamiliar Repo Is a Security Boundary

Adamma — Sun, 07 Jun 2026 19:43:28 +0000

Overview

Running an unfamiliar repo is not neutral.

That first command can install packages, execute lifecycle scripts, create files, start services, request credentials, open network connections, apply migrations, seed data, or touch external systems.

That does not mean every repo is dangerous.

It means the first run is a boundary.

And my view is simple: boundaries should be inspected before they are crossed.

This is one of the clearest reasons Ota exists. Ota is not just about making repos easier to run. It is about making repo execution explicit before humans, CI, automation, or AI agents start acting on trust they have not earned yet.

The old developer habit is:

Clone the repo.
Run the setup command.
See what breaks.

That habit is too casual for modern software.

The better habit is:

Inspect the repo.
Understand what execution will do.
Preview the declared path.
Then run it.

That is the shift from repo setup as guesswork to repo execution as a governed action.

The First Run Is Not Just Setup

When people say "just run the repo," they usually flatten a lot of behavior into one harmless-sounding sentence.

But the first meaningful execution step in a repo can include:

dependency installation
package-manager lifecycle scripts
local file creation or mutation
long-running service startup
container creation
database migrations
seed data
secret requirements
external API calls
changes to remote systems

For a maintainer, that may all feel normal.

For a new contributor, it is not normal.

For an AI agent, it is worse. The agent may choose the obvious command because it is the strongest visible signal, not because it understands the consequences.

That is not mainly a prompting problem.

It is a repo execution problem.

A Repo That Runs Can Still Be Opaque

A repo is not trustworthy just because it eventually starts.

If the setup path installs dependencies, starts services, applies migrations, and seeds data, then "it worked on my machine" still leaves the important questions unanswered:

what exactly ran
what changed
what required secrets
what talked to the network
what touched external systems
what was safe for automation
what should have been reviewed before execution

That is why "can this repo run?" is not enough.

The stronger question is:

What will this repo do when I run it?

If the repo cannot answer that clearly, the first run is still a trust fall.

Most Risk Hides Inside Ordinary Commands

The risky part is usually not an obviously scary command.

It is usually something ordinary:

install
setup
dev
test
seed
migrate
start

Those names look harmless. Sometimes they are. Sometimes they hide real side effects.

A setup task may install packages and generate files.

A dev task may start multiple services and keep running forever.

A test task may require a database and mutate fixtures.

A seed task may write data.

A migrate task may alter schema.

A start task may assume credentials are already present.

The problem is not that these tasks exist.

The problem is that most repos do a weak job of declaring what they mean before execution.

My opinion here is direct: if a repo expects humans or agents to run tasks, the repo should declare what those tasks actually do. README hints and command names are not enough.

Why This Matters More For AI Agents

AI agents compress the distance between reading and acting.

A human might pause before running a strange command. An agent often will not, unless the repo makes the stopping rules explicit.

If an agent sees setup, it needs to know whether that command:

only installs dependencies
starts services
requires secrets
mutates local state
touches external systems
is safe for automation at all

This is why "be careful" is not a serious safety model.

If a task requires credentials, the agent should stop.

If a task touches external systems, the agent should stop unless approved.

If a task is outside declared safe tasks, the agent should stop.

If the requested work touches protected paths, the agent should stop.

That is how agent safety becomes operational.

Not by hoping the agent is cautious.

By making the repo declare where execution should stop.

First-Run Inspection Should Be Normal

Before running an unfamiliar repo, the responsible question is not:

What command do I try first?

It is:

What will this repo do when I run it?

A healthy repo should let you inspect that before mutation starts.

At minimum, first-run inspection should reveal:

required runtimes and tools
setup and bootstrap tasks
service dependencies
environment requirements
tasks that are safe to run
tasks that should stop for approval
protected paths
external state or network effects
verification tasks
blockers that prevent execution safely

If that sounds strict, good. It should be strict.

Repos are executable systems, not just folders of source code.

This Is Exactly Where Ota Fits

Ota treats first-run execution as something the repo should declare, preview, and govern.

That starts with the repo-local ota.yaml.

The contract can declare:

what the repo needs
how it becomes ready
which tasks exist
which workflows are the intended front door
which tasks are safe for agents
which paths are writable or protected
which effects require caution
what counts as ready

That gives humans, CI, automation, and AI agents one inspectable operating path before execution.

The Ota discipline is simple:

Inspect before acting.
Diagnose before mutating.
Preview before setup.
Run declared safe tasks.
Stop at secrets, unsafe mutation, protected paths, or external-state boundaries.
Return stable status.

That is not process theater.

That is what a governed first run looks like.

The Best Ota Commands For First-Run Inspection

If you want this behavior to be real, not rhetorical, the command surface matters.

These are the important ones:

ota doctor tells you what is missing or blocked before execution
ota validate checks whether the contract itself is sound
ota tasks --json exposes declared work in a machine-readable way
ota up --dry-run previews the setup path before changing the environment
ota run <task> --dry-run --json previews execution intent and status for automation

The most important command in this post is ota up --dry-run.

That command matters because setup should not begin with mutation. It should begin with inspection.

README Prose Is Not A Boundary

This is the part I would state bluntly.

README instructions are helpful, but they are not execution governance.

AGENTS.md is helpful, but it is not execution governance either.

A warning like:

Be careful with database commands.

is not a boundary.

A boundary is:

these tasks are safe
these paths are protected
these secrets are required
these external systems require approval
these effects are denied
this workflow is the intended front door

That difference matters because humans forget, READMEs drift, and agents act on the strongest signal they see.

If the repo never makes the boundary explicit, the first run is still governed by guesswork.

The Better Standard

The old standard was convenience:

Can I get this repo running?

The better standard is governance:

Can I inspect what this repo will do before I run it?

That is the standard Ota is pushing.

Not just runnable repos.

Inspectable repos.

Not just setup docs.

Declared execution truth.

Not just telling agents to behave.

Giving the repo explicit stop signs.

Conclusion

Running an unfamiliar repo is a security boundary, whether teams name it that way or not.

The first run can install, execute, start, connect, mutate, request, or verify. Sometimes that is exactly what you want. Sometimes it is not.

The difference should not be discovered accidentally by typing the obvious command.

Ota treats first-run behavior as something to inspect before execution, govern through a repo contract, and verify through declared tasks, workflows, and stable output.

That is what software execution governance means in practice.

Not just making repos runnable.

Making execution understandable before it happens.

Explore the Ota getting started guide
Check out the Ota examples repo

Originally posted @ ota.run

AI Agent Safety Need Stop Signs, Not Just Instructions

Adamma — Sun, 07 Jun 2026 08:09:00 +0000

AI agents do not only need better instructions.

They need stop signs.

That is one of the clearest reasons Ota exists as software execution governance for humans and AI agents. A repo should not merely tell an agent what it can try. It should declare what the agent must not do, when it must stop, and what requires human approval.

Prompts and AGENTS.md files are useful. They give agents context: how the project is organized, what style to follow, how to summarize changes, and which areas need caution.

But advice is not a boundary.

An instruction says:

Be careful with database commands.

A stop sign says:

Do not run destructive database commands unless explicitly approved.

An instruction says:

Avoid editing generated files.

A stop sign says:

These paths are protected. Stop if the requested edit falls outside the writable boundary.

That difference matters because modern agents are no longer passive readers. They inspect repos, choose commands, edit files, run checks, interpret failures, and report completion.

If the repo gives them only guidance, they still have to infer the boundary.

Ota’s position is sharper: agent execution should not depend on inference. It should be governed by the repo.

Instructions tell agents what to attempt

Most agent guidance is written as advice.

It says:

follow the existing style
prefer small changes
run tests before finishing
avoid touching generated files
do not expose secrets
explain what changed

That helps. It makes agents less generic and more aware of the repo they are working inside.

But it still leaves the dangerous questions open.

Which tests should the agent run?
Which commands are allowed?
Which files are generated?
Which services require approval?
Which failures mean “fix the code” and which mean “stop and ask”?
Which paths are out of bounds?

A capable agent may make reasonable guesses.

But reasonable guesses are not governance.

For low-risk editing, guidance may be enough. For repo execution, CI, automation, and agentic development, the repo needs something stronger.

Stop signs define when not to continue

A stop sign is not a suggestion.

It is a boundary.

In a repo, stopping rules should cover at least five areas.

1. Secrets and credentials

An agent should not invent secrets, request private values indirectly, or edit sensitive environment files just to make a task pass.

If a command needs an API key, database password, cloud token, or private credential, the correct behavior is not improvisation.

The correct behavior is to stop and report the blocker.

2. External services

Some tasks depend on systems outside the repo: cloud infrastructure, managed databases, payment providers, queues, object storage, or production-like services.

If those services are unavailable, the agent should not patch code around the failure.

It should identify the missing dependency and stop.

3. Unsafe mutation

Some commands change state.

deploy
publish
db:reset
terraform apply

These are not cousins of test, lint, or build.

If a task can mutate external state, delete data, publish packages, or affect infrastructure, the repo should not outsource that decision to the agent’s confidence.

That boundary should be declared.

4. Protected paths

Agents need to know where they can work.

Source files and tests may be open. Generated files, migrations, lockfiles, production config, and environment files may need review or approval.

This is not about slowing the agent down.

It is about preventing quiet damage in files that carry operational weight.

5. Verification limits

Agents also need to know when verification is finite.

A long-running dev server is not a verification result.
A watch mode is not a handoff signal.
A task that never terminates is not the same as a bounded check.

Agent-safe tasks need finite verification paths: run, finish, report status.

Without that, the agent may wait indefinitely, stop too early, or report success without a meaningful result.

This is execution governance

This is bigger than prompt quality.

If an agent runs a risky command, edits a protected file, or treats missing credentials as a code problem, the issue is not only that the agent made a poor choice.

The repo failed to govern execution.

Software execution governance means the repo can declare:

what it needs
how it should be prepared
what can be executed
what requires approval
where agents can write
when verification is complete
when execution must stop

That is the frame Ota is built around.

Not “better setup docs.”

Not “another task runner.”

Ota is the contract-first way to make execution boundaries explicit for humans, CI, automation, and AI agents.

How Ota makes stop signs explicit

In an Ota-backed repo, stopping rules do not have to live only in prose.

The contract can declare safe tasks, verification tasks, writable paths, protected paths, setup requirements, and readiness blockers.

That gives agents a governed operating model:

If the task is declared safe, proceed.
If setup is required, prepare from the contract.
If the contract is invalid, stop.
If secrets or credentials are missing, stop.
If the requested edit is outside writable paths, stop.
If the task mutates external state without approval, stop.
If verification is complete, report the result.

That is stronger than telling an agent to “be careful.”

Ota’s agent quickstart follows this same principle: agents should prefer repo-local contracts when they exist, execute declared safe tasks, parse JSON output instead of scraping terminal prose, and stop when blockers involve secrets, credentials, external services, unsafe mutation, or paths outside declared boundaries.

The command surface supports that model:

ota doctor checks readiness and surfaces blockers before work begins.
ota validate checks whether the contract itself is usable.
ota tasks shows what work the repo has declared.
ota up --dry-run previews setup before changing the environment.
ota run <task> --json runs declared work and returns stable status for automation.

The point is not that every agent action needs ceremony.

The point is that dangerous ambiguity should be removed before execution happens.

AGENTS.md still matters

This does not make AGENTS.md useless.

It means AGENTS.md should do what prose does best: explain context.

Use it for style, conventions, architectural notes, review expectations, and collaboration preferences.

Use Ota for the execution boundary.

A clean split looks like this:

AGENTS.md:
How the agent should behave.

ota.yaml:
What the repo allows, requires, verifies, and refuses.

One gives the agent context.

The other governs the repo.

Together, they produce a better operator: one that understands the project and knows where the guardrails are.

Stop signs build trust

Teams do not trust agents because agents sound confident.

They trust agents when the repo constrains what the agent can do, makes the approved path obvious, and produces evidence for what happened.

A good stop sign does not make agents less useful.

It makes them dependable.

It tells the agent:

Move quickly here.
Slow down here.
Stop here.
Ask here.
Report this.
Do not guess.

That is the behavior serious teams need as AI agents move from code suggestion into repo execution.

Conclusion

AI agents need instructions.

But instructions alone are not enough.

A repo that only tells agents what to do still leaves too much room for unsafe interpretation. The next layer is stopping rules: clear boundaries for secrets, external services, unsafe mutation, protected paths, and finite verification.

That is why Ota’s contract-first model matters.

It turns agent safety from advice into execution governance.

The future of AI-assisted development will not be won by repos that merely prompt agents better.

It will be won by repos that know when agents should stop.

Explore the Ota getting started guide
Check out the Ota examples repo

Originally posted @ ota.run

Diagnose with Ota, Then Run with Confidence

Adamma — Sat, 06 Jun 2026 11:04:19 +0000

Most repo blockers are discovered too late.

A developer clones a repo, follows the README, runs the setup command, and only then finds out that the required runtime is missing. Or Docker is not running. Or the test database needs secrets they do not have. Or the command they ran was never the command CI uses.

By then, the repo has already wasted their time.

With AI agents, the cost is higher.

An agent can inspect files, choose commands, edit code, and run tests. But if the repo does not surface blockers early, the agent may spend its effort on the wrong thing. It may treat a missing service as a code bug. It may retry a command that was never going to work. It may make changes before realizing the repo was not ready to execute safely.

This is exactly the class of problem Ota is built to solve.

Ota’s position is straightforward: a repo should not force humans, CI, or agents to discover basic execution blockers halfway through work. The repo should expose them up front, before execution begins, through one explicit contract for execution governance.

That is why the better habit is simple:

Diagnose first.
Run second.

A blocker is not always a failure

A blocker is not the same as a bug.

A bug says the software behaved incorrectly.

A blocker says execution should not proceed yet.

If Postgres is not running, the app may fail. But the failure does not mean the application logic is wrong. It means the environment is incomplete.

If an API key is missing, a test may fail. But the fix is not necessarily in the codebase. It may require secrets, access, or user approval.

If the repo requires Python 3.12 but the machine has Python 3.10, the build may fail before the project itself has even been tested.

These are execution blockers.

They should be surfaced before the repo asks humans, CI, or agents to do meaningful work.

Why late blockers are expensive

Late blockers are expensive because they look like ordinary failures.

A missing service looks like a broken test.
A missing runtime looks like a dependency issue.
A missing environment variable looks like an application error.
A risky command looks normal until it mutates state.

For humans, this creates frustration.

For CI, it creates noisy failures.

For agents, it creates bad decision paths.

An agent may see a stack trace and try to patch the code. But if the real blocker is missing Redis, the agent is now solving the wrong problem. It may edit files, rerun tests, and report uncertainty when the correct next step was simply: start the required service or stop and ask for credentials.

Early diagnosis prevents that wrong turn.

What should be diagnosed first?

A repo does not need to diagnose everything before running code.

It needs to diagnose the conditions that decide whether execution is safe and useful.

At minimum, that includes:

required runtimes
required package managers
required tools
expected services
required environment variables
setup prerequisites
task availability
safe tasks for agents
protected paths
whether the requested action needs external state

This is not about adding friction.

It is about avoiding work that could never produce a trustworthy result.

If a task needs Docker, check that early. If a test requires Postgres, say that early. If an agent is not allowed to mutate external state, stop before it reaches the risky command.

Diagnose first does not mean never run

There is a bad version of this idea:

“Check so much that nothing ever executes.”

That is not the goal.

The goal is to make the next action obvious.

If the repo is ready, run the declared task.

If the repo is blocked, show the blocker.

If the repo needs approval, stop and ask.

If the repo requires secrets, do not invent them.

If the task is outside the safe boundary, do not pretend it is safe.

Good diagnosis should lead to movement. It should answer one practical question:

What is the next safe action?

What this looks like for AI agents

For AI agents, blocker diagnosis is a guardrail.

Before acting in a repo, an agent should know whether the repo exposes execution governance, which tasks exist, which tasks are safe, and where execution should stop.

A safer Ota-backed agent loop looks like this:

1. Run `ota doctor`.
2. Run `ota validate`.
3. Run `ota tasks --safe --use`.
4. Preview setup with `ota up --dry-run` when needed.
5. Run only declared safe tasks through `ota run <task>`.
6. Stop when blockers require secrets, external services, or unsafe mutation.
7. Report the blocker and the next safe action.

This is not about making agents timid.

It is about keeping agent execution bounded.

A good agent should move quickly when the repo is ready and stop clearly when the repo is not.

Ota should surface blockers before execution

This is one of the clearest places where Ota’s framing matters.

A blocker should not be discovered only after a human, CI job, or agent has already started running commands. The repo should be able to surface basic execution problems before execution begins.

In an Ota-backed repo, that means the contract can describe what the repo needs, which tasks exist, which tasks are safe, and where execution should stop. Ota’s agent guidance follows the same rule: prefer the repo contract when it exists, execute only declared safe tasks, consume JSON output when automation needs it, and stop when blockers require secrets, credentials, external services, unsafe mutation, or paths outside the declared boundary.

For example:

ota doctor surfaces execution blockers before work starts.
ota validate checks whether the contract itself is usable.
ota tasks --safe --use shows what work an agent can actually run safely.
ota up --dry-run previews setup before changing the environment.
ota run <task> --json runs declared work and returns stable status for automation.

The point is not simply to put commands behind another CLI.

The point is to avoid guessing whether execution should proceed, whether the task is safe, or whether the result means anything.

That is the difference between reactive execution and governed execution.

The human benefit

This is not only for agents.

A repo that diagnoses blockers early is easier for humans too.

New contributors know why setup is blocked.
Maintainers get fewer vague “it does not work” reports.
CI can fail earlier with clearer messages.
Automation can stop before mutating state.
Agents can report blockers instead of hallucinating fixes.

The practical outcome is simple: less time spent debugging the wrong layer.

Instead of asking:

Why did this command fail?

The repo helps answer:

Was this command safe and useful to run in the first place?

That is a better question.

Conclusion

Running code is not always the first responsible step.

Sometimes the responsible step is diagnosis.

A repo should be able to say what it needs, what is missing, what is safe, and what should happen next before execution begins.

That does not make development slower. It makes execution more intentional.

The old habit is:

Run the command and see what breaks.

The better habit is:

Diagnose first. Run second.

That is how teams move from accidental execution to software execution governance.

If you want that behavior to be explicit instead of tribal, start with ota doctor and give the repo one contract that can say what is blocked, what is safe, and what the next action should be before anyone starts guessing.

Explore the Ota getting started guide
Check the Ota examples repo

Why a Runnable Repo Is Not Always a Trustworthy Repo

Adamma — Thu, 04 Jun 2026 20:07:59 +0000

A repo can run and still be hard to trust.

That sounds strange at first. If the app starts, the build completes, or the tests pass, the repo is working, right?

Not always.

A runnable repo proves that something executed under some conditions. A trustworthy repo explains those conditions, makes the path repeatable, and gives humans, CI, automation, and AI agents enough evidence to understand what happened.

That difference matters more as software teams rely on AI-assisted development.

For a human, an unclear repo creates friction. For an AI agent, it creates risk. The agent may run the obvious command, get a passing result, and assume the repo is healthy, even though the result only proves a small part of the system.

The next standard is not just:

Can this repo run?

It is:

Can this repo be trusted when it runs?

Runnable is a low bar

A repo is runnable when someone can get it to execute.

Maybe the app starts locally. Maybe one test command passes. Maybe the build completes on a maintainer’s machine.

That is useful, but it does not answer enough questions.

A runnable repo may still leave important things unclear:

Which runtime and tool versions were used?
Was setup completed correctly?
Were required services running?
Was this a quick check or the full verification path?
Was the command safe for automation?
Did the result match what CI expects?
Can someone else reproduce the same outcome?

If those answers are missing, the repo may run, but the result is difficult to interpret.

That is the gap between execution and trust.

Trustworthy repos make conditions explicit

A trustworthy repo does not only provide commands. It explains the conditions around those commands.

For example, this is runnable:

pytest

But this is more trustworthy:

Runtime:
Python 3.12

Services:
Postgres 16 must be running

Quick check:
pytest tests/unit

Full verification:
pytest --cov
ruff check .
mypy .

The first version tells someone what to run.

The second tells them what the result means.

That distinction matters. If an AI agent runs pytest and sees a pass, it may report success. But if the repo’s real verification path also includes coverage, linting, type checks, and database-backed integration tests, that success is incomplete.

The command ran.

The repo was not fully verified.

Trustworthy repos reduce false confidence

The dangerous thing about an unclear repo is not only failure.

It is false confidence.

A failure forces someone to investigate. A misleading pass can be worse because it tells the human, CI job, or agent that things are fine when they are not.

This happens when:

local checks are weaker than CI checks
README commands are outdated
service dependencies are implicit
generated files are skipped
migrations are not tested
safe and risky commands are mixed together
agents treat a small local check as full verification

In these cases, the repo may produce green output without producing meaningful assurance.

That is not only a testing problem.

It is an execution governance problem.

The repo has not made clear what counts as enough evidence.

Trustworthy repos define safe execution

A repo also becomes more trustworthy when it separates safe execution from risky execution.

Some commands are usually safe:

test
lint
typecheck
build

Others may need explicit approval:

deploy
publish
db:reset
terraform apply

For humans, the difference may be obvious from experience. For automation and AI agents, it should be declared.

The same applies to files.

Source code and tests may be safe to edit. Generated files, production config, lockfiles, migrations, and environment files may need stronger review.

A trustworthy repo does not rely on an agent guessing those boundaries from filenames.

It makes safe paths visible.

Trustworthy repos create evidence

A runnable repo says:

The command ran.

A trustworthy repo can say more:

what command ran
what setup happened first
what environment was expected
what task was selected
what passed or failed
what was skipped
what still needs review

That evidence matters for humans. It matters for CI. It matters even more for agents.

When an agent reports that work is complete, the team needs to know whether it ran the right task, in the right context, with the right boundaries.

Without evidence, agent output becomes another thing to manually verify from scratch.

With evidence, automation becomes easier to trust.

The contract layer

This is where the earlier posts in this series have been pointing.

Once a repo needs to be trusted by humans, CI, automation, and AI agents, scattered instructions are not enough. The repo needs a contract layer: a declared place where setup, tasks, safety boundaries, verification, and execution expectations can be reviewed together.

That is the role Ota’s ota.yaml is designed to play.

The important shift is not “use another config file.”

The shift is:

From:
This repo has commands you can try.

To:
This repo declares how execution should happen, what is safe, and what evidence counts.

In that model, ota doctor can check readiness before work starts. ota validate can check whether the contract itself is valid. ota up can prepare the repo from declared setup. ota run <task> can execute declared work instead of forcing humans or agents to guess the right command.

The value is not only that tasks run.

The value is that execution becomes explicit, bounded, and reviewable.

That is what moves a repo from runnable toward trustworthy.

The better standard

The old standard was:

Can I run this repo?

The better standard is:

Can I trust what happened when this repo ran?

That requires more than a command.

It requires clear setup, declared tasks, safe execution boundaries, verification paths, and evidence.

This is especially important for AI agents because they are increasingly expected to operate inside repos, not just read them.

They need to know what is safe.
They need to know what counts as verification.
They need to know when to stop.
They need to know what to report.

A trustworthy repo makes those answers visible.

Conclusion

A runnable repo is useful.

But a runnable repo is not always a trustworthy repo.

It may start, build, or pass a small test while still hiding the conditions that made the result possible. It may produce green output without proving the repo is ready. It may let humans, CI, and agents interpret success differently.

That is why repo readiness is only the beginning.

The larger goal is execution governance: making software execution explicit, safe, verifiable, and reusable across humans, CI, automation, and AI agents.

A repo you can run saves time.

A repo you can trust changes how safely people and agents can work.

Explore the Ota getting started guide
Check the Ota examples repo

Originally posted: https://ota.run/blog/runnable-repo-vs-trustworthy-repo

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.

AGENTS.md vs Ota: Instructions vs Readiness Contracts

Adamma — Wed, 03 Jun 2026 20:13:41 +0000

AGENTS.md is a useful idea.

It gives AI agents a place to look for repo-specific instructions: how the project is organized, what conventions to follow, what files to avoid, and what commands may be useful.

That is valuable.

The problem starts when teams expect AGENTS.md to carry the full weight of repo readiness.

An instruction file can guide an agent. It can explain intent. It can warn against risky changes. But it is still prose.

It cannot prove the repo is ready.
It cannot validate that setup still works.
It cannot guarantee that a command exists.
It cannot make CI, humans, and agents share the same execution path.

That is the difference between instructions and readiness contracts.

What AGENTS.md is good for

An AGENTS.md file is best at giving agents human-written context.

For example, it can explain:

how the repo is structured
which coding conventions to follow
what areas need extra caution
how to write tests
what files are generated
what commands are usually useful
how to summarize changes

This kind of guidance helps agents behave less like generic code generators and more like collaborators inside a specific repo.

A good AGENTS.md can reduce noise. It can tell an agent not to edit generated files, not to touch production config, or not to run destructive database commands.

That matters.

But AGENTS.md works best as an instruction layer, not as the repo’s execution authority.

Where AGENTS.md starts to fall short

The limitation is simple: prose can drift.

An AGENTS.md file may say:

Run the tests before finishing.

But which tests?

Unit tests? Integration tests? Type checks? Lint? Build? The same command used locally, or the stricter command used in CI?

It may say:

Do not edit generated files.

But which paths are generated? Are they listed explicitly? Are they enforced anywhere?

It may say:

Start the database before running integration tests.

But how should the database be started? Which version? Which port? How does the agent know it is ready?

These instructions are useful, but they are not executable by themselves.

They depend on the agent interpreting prose correctly and on the prose staying current as the repo changes.

That is risky when the agent is expected to run commands, edit files, and verify work.

What a readiness contract adds

A readiness contract turns repo expectations into structured, reviewable rules.

Instead of only saying what an agent should generally do, the repo declares what it needs and how work should run.

A contract can describe:

required runtimes and tools
setup tasks
declared commands
task dependencies
safe tasks for agents
protected paths
verification steps after changes
expected execution mode

That changes the operating model.

The agent no longer has to infer the repo’s setup path from scattered prose, package scripts, CI files, and README notes. The repo has a declared source for readiness and execution.

This is why Ota uses ota.yaml.

Ota’s docs describe a starter ota.yaml as a contract that names the repo, declares core runtime and tools, defines safe tasks and verification tasks, and gives agents a deterministic entrypoint.

That is a different category from instruction prose.

Instructions tell. Contracts govern.

This is the simplest way to understand the difference:

AGENTS.md tells the agent how to behave.

ota.yaml tells the repo how execution is governed.

Those two things can work together.

AGENTS.md can say:

Prefer small changes.
Explain what you changed.
Do not edit generated files manually.
Run the appropriate verification task before handoff.

An Ota contract can define:

The setup task is safe.
The test task depends on setup.
The build task must run before test.
The agent may run setup, build, and test.
The agent should verify changes with build and test.
These paths are protected.

The instruction file provides context. The readiness contract provides structure.

One is guidance. The other is an operating boundary.

Why this matters for AI agents

AI agents are increasingly expected to do more than suggest edits.

They inspect a repo, choose commands, change files, run tests, interpret failures, and report whether work is complete.

That means they need more than “please be careful.”

They need the repo to expose safe, finite, verifiable paths.

Without that, an agent may run a helpful-looking command that is not the real verification path. It may skip setup. It may edit a protected file. It may treat a missing tool as a code failure. It may report success after passing a small local check while CI would still fail.

These are not always model failures.

They are governance failures.

The repo did not make the safe path explicit enough.

Where Ota fits

Ota is software execution governance for humans and AI agents.

It helps a repo declare what it needs, how it should be prepared, what can be safely executed, and how work should be verified.

With Ota, humans, CI, automation, and AI agents can work from the same repo-level contract instead of guessing from READMEs, scripts, CI files, and scattered configuration.

A typical Ota loop looks like this:

ota doctor checks whether the repo is ready and points to the blocker.
ota validate checks whether the contract itself is valid.
ota up prepares the repo from the contract.
ota run <task> runs declared work through the contract.

The value is not just command execution.

The value is that execution becomes explicit, bounded, and reviewable.

The better model: AGENTS.md plus Ota

This should not be framed as AGENTS.md versus Ota in a winner-takes-all sense.

The better model is both.

Use AGENTS.md for repo-specific guidance, collaboration style, coding conventions, and human-readable cautions.

Use Ota for readiness, setup, execution, verification, task boundaries, and agent-safe operations.

That gives you a cleaner split:

AGENTS.md:
Human-readable instructions for how an agent should behave.

Ota:
Machine-readable execution governance for what the repo allows, requires, and verifies.

When those two layers agree, agents get both context and structure.

They know how to behave, and they know what the repo is prepared to run.

Conclusion

AGENTS.md is useful, but it should not be asked to do everything.

It can explain how an agent should work inside a repo. It can capture conventions, preferences, and warnings.

But repo execution needs more than instructions.

It needs a readiness contract that can declare setup, safe tasks, protected paths, verification steps, and execution rules in a form humans, CI, and agents can share.

That is where Ota fits.

Instructions help agents understand the repo.

Readiness contracts help the repo govern execution.

Continue reading

Check out Repo Readiness for AI Agents: The Complete Guide
Explore the Ota getting started guide
Check the Ota examples repo for practical contract examples.

Originally Posted:https://ota.run/blog/agents-md-vs-ota-yaml-instructions-vs-readiness-contracts