DEV Community: Adamma

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

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

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

How to Align Local, CI, and Agent Execution

Adamma — Sat, 30 May 2026 11:48:22 +0000

Overview

One of the fastest ways to make a repo unreliable is to let local development, CI, and agent execution drift into three different stories.

A developer runs one command locally. CI runs a stricter path in a different environment. The agent reads the README, checks package scripts, opens the workflow file, and has to guess which version of the repo is actually true.

That is where bad automation starts.

The code may be fine. The failure is often operational. The repo never made its intended execution path clear enough for humans, CI, and agents to follow the same logic.

Drift Starts Quietly

Execution drift usually does not arrive as a big design decision. It grows out of convenience.

A project starts with something simple:

npm test

Later, CI gets stricter:

pnpm install --frozen-lockfile
pnpm lint
pnpm typecheck
pnpm test:ci

Then the repo grows again. A service moves into Docker. Integration tests need Postgres. A new environment variable shows up. The README stays broad, CI becomes the only place with the full path, and local scripts explain only part of the story.

Now the repo has multiple sources of operational truth.

Humans feel that as "it works on my machine." Agents feel it as conflicting signals. They run the most obvious command, get a partial pass, and report success against a repo that would still fail in CI.

That is not always an agent reasoning failure. A lot of the time, the repo gave incomplete instructions.

Alignment Does Not Mean Identical Commands

Alignment does not require local development, CI, and agents to run the exact same command sequence.

Local workflows can stay fast. CI can stay strict. Agents can have tighter safety boundaries than maintainers.

What has to stay aligned is the intent.

Local:
Run fast checks before and during development.

CI:
Run the full verification path before merge.

Agent:
Run declared safe tasks, report what passed, and stop cleanly at boundaries.

The problem starts when each path is invented separately instead of declared from the same operating model.

What To Align First

The best place to start is with the parts of the repo that create the most confusion and the most false confidence.

1. Setup

There should be one clear setup path for the repo.

For a Python service, that might be:

poetry install
docker compose up -d postgres
poetry run alembic upgrade head

For a Go service, it might be:

go mod download
docker compose up -d redis
go test ./...

The stack is not the point. Clarity is. Setup should not be split across README prose, CI YAML, shell history, and one teammate's memory.

2. Tasks

Repos should expose common tasks with clear names.

setup
test
test:integration
lint
typecheck
build
dev

People and agents both work better when task names explain intent. If someone has to inspect every script to figure out what is quick, complete, safe, or destructive, the repo is already too ambiguous.

3. Verification

Verification is where drift becomes expensive.

A repo should separate quick feedback from full verification:

Quick check:
pytest tests/unit

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

Without that distinction, contributors stop at the fast check and assume they are done while CI still holds the real standard.

4. Services

Services should never be implied.

If a task needs Postgres, Redis, Elasticsearch, a queue, or a local emulator, the repo should say so directly. It should also say whether that service is started with Docker Compose, expected from the host machine, or provided elsewhere.

This matters because missing services often look like application bugs. An agent can lose time chasing the wrong problem when the real issue is that the repo never declared its dependencies clearly.

5. Safety Boundaries

Agents need a clean line between what is safe to run and what requires review.

Safe tasks usually look like:

test
lint
typecheck
build

Riskier tasks usually look like:

deploy
publish
db:reset
terraform apply

If that boundary is not explicit, the agent is left inferring safety from command names. That is not a serious operating model.

Where Ota Fits

This is the problem Ota is meant to solve.

Ota turns repo execution from scattered instructions into a declared contract. Instead of hoping the README, scripts, and CI happen to agree, the repo can describe its readiness model in ota.yaml.

That contract can declare:

what the repo needs
how setup happens
which tasks exist
which workflow is expected
what counts as readiness
which commands are safe for agents

The value is not just that Ota can run commands. The value is that humans, CI, and agents can all operate from the same declared path.

For example:

ota doctor checks whether the repo is actually ready and points to the blocker
ota validate checks whether the contract is valid
ota up prepares the repo from the declared contract
ota run <task> runs a declared task instead of forcing people or agents to reverse-engineer the right command

The README can still explain the project. CI can still enforce the standard. Ota gives them a shared execution contract so they stop drifting apart.

A Simple Alignment Check

Before adding more setup prose to a README, it is worth asking:

Can a new contributor find the correct setup path?
Does CI prove the same core tasks the repo tells people to run?
Is the difference between quick checks and full verification explicit?
Are required services declared clearly?
Are dangerous commands separated from safe ones?
Can an AI agent tell what it is allowed to run?
Is there one place that explains how execution is supposed to work?

If the answer is no, the repo does not mainly need more documentation. It needs better alignment.

Closing

Local development, CI, and AI agents usually fail for the same boring reason: the repo never made its intended execution path explicit enough.

That gets more expensive as teams depend more on automation and AI-assisted development.

A ready repo should tell humans what to run, tell CI what to enforce, and tell agents what is safe.

That is alignment.

Not identical environments.

A shared path.

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/how-to-align-local-ci-and-agent-execution

Is Ota another Makefile?

Adamma — Tue, 26 May 2026 21:55:33 +0000

One question about Ota keeps coming up:

"Isn't this just a Makefile with extra steps?"

It's a fair question.

Makefiles are one of the most familiar ways to expose a command surface in a repository. If you see a Makefile, you expect targets like:

make test
make build
make dev
make install

That's useful. Makefiles have lasted because they solve a real problem: shared command shortcuts.

Ota is not anti-Makefile, and it is not trying to remove familiar command ergonomics.

A Makefile usually answers:

What command should I run?

Ota answers:

Is this repo actually ready to run, and what must be true for that to stay repeatable?

That difference matters.

Another way to say it:

Ota includes Makefile-style task execution, then adds first-class readiness around it.

What Makefiles are great at

Makefiles are excellent for common repo actions.

Instead of asking contributors to remember command sequences, teams define targets once and reuse them. That reduces command hunting and improves ergonomics.

What Makefiles usually do not do is model readiness state. They typically don't tell you:

the runtime version is wrong
a required env var is missing
Docker is required but not running
docs, local setup, and CI have drifted

So when make test fails, people fall back to detective work.

That's not a Makefile bug. It's just outside the Makefile's job.

The problem Ota focuses on

Ota is an open-source CLI for repo readiness.

A repo declares an explicit readiness contract (typically ota.yaml) describing what must be true for setup and execution to be reliable and diagnosable.

That contract can define:

runtimes
tools
setup requirements
tasks and workflows
environment expectations
safe task boundaries
readiness checks

Ota does not magically invent a working path. Maintainers still establish that first path. Ota's value is turning that path into explicit, repeatable contract truth.

Our core line is:

Make the first working run repeatable.

Because "it worked once" is not enough for the next contributor, CI run, automation, or agent.

Where Ota extends Make

A Makefile is primarily a recipe layer.

Ota is a recipe plus readiness layer.

A Make target might say "run tests."

Ota models the operational truth around that task:

Is the repo ready?
What is missing?
What is blocking vs warning?
Which workflow path should run?
Which runtime/tooling is required?
What is the next safe step?

Core commands:

ota doctor — diagnose readiness, blockers, warnings, and next actions
ota validate — validate contract quality before relying on it
ota up — prepare repo from declared contract intent
ota run <task> — execute declared tasks through the same operational path used by humans, CI, and agents

So the real question is not "Make or Ota?"

It is:

Do you only need command shortcuts, or do you need verifiable readiness?

Concrete example

A common flow looks like this:

make test

If it fails, you still need to figure out whether the issue is code, missing setup, wrong runtime, missing services, or config drift.

With Ota, the flow becomes explicit:

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

That gives one diagnosable path:

ota doctor explains readiness blockers and the next action
ota up --dry-run previews preparation before mutation
ota run test executes the declared test path used by humans, CI, and agents

Why this matters more now

This always mattered for humans. It matters even more with AI-assisted development.

Agents can discover commands, but they still need operational context:

what is safe to run
what prerequisites must hold first
whether a failure is code-related or readiness-related
whether the path is native, container, or remote

A Makefile can expose commands.

Ota exposes readiness meaning around those commands.

Who should use this now

Use this model now if your team has one or more of these conditions:

onboarding is slow because setup truth is split across multiple files
CI/local behavior drifts and root-cause takes too long
repos have native plus container paths and ownership is ambiguous
teams rely on AI-assisted changes and need explicit safe execution boundaries

Ota can work with Makefiles

Ota does not require replacing Make.

In many repos, the best outcome is Make + Ota:

Make keeps familiar recipes.
Ota defines readiness truth around those recipes.

Example: keep make test, and define an Ota task that calls it plus readiness requirements for that workflow.

Make owns recipes. Ota owns readiness semantics.

So, is Ota another Makefile?

Not exactly.

Ota can absolutely cover Makefile-style command surfaces.

The difference is that Ota also explains and verifies readiness: whether the repo is ready to run, why it is blocked when it isn't, and how to keep the working path repeatable across humans, CI, automation, and AI agents.

Make is great for recipes.

Ota gives you recipes plus readiness.

As repos become more complex and more automated, that readiness layer is harder to ignore.

Makefile gives commands. Ota gives command truth.

Get Started with Ota

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

Originally Posted: https://ota.run/blog/is-ota-another-makefile-56bh

Why README-Driven Infrastructure Breaks for AI Agents

Adamma — Sat, 23 May 2026 13:47:06 +0000

A README is supposed to be the front door of a software project.

It tells people what the repo does, why it exists, how to get started, and where to look next. That role still matters. A good README helps humans understand the project before they touch the code.

The problem starts when the README becomes more than documentation.

In many repos, the README quietly becomes the setup system, onboarding guide, task registry, local development manual, and source of truth for how work should happen.

That is README-driven infrastructure.

It works until the repo changes faster than the prose does.

The README still says npm test, but CI now runs pnpm test:ci. The README says “install Python,” but the app actually needs Python 3.12, Poetry, Docker, and Postgres.

A README is excellent for explanation. It is weak as the only place where a repo’s working state lives.

How README-driven infrastructure works in practice

README-driven infrastructure happens when operational truth lives mainly in README prose.

The README might be the only place that explains:

which runtime version the repo needs
which package manager to use
how to install dependencies
which services must be running
what environment variables are required
which command runs the real test suite
which files or commands are unsafe for automation
what to run after making a change

At first, this feels fine. A clear README is better than no README.

But prose drifts.

A team updates CI but forgets to update the README. The project switches from npm to pnpm. Tests start requiring Postgres or Redis. The real verification path moves into a workflow file. The README still shows the old happy path.

Humans can sometimes work around this. They inspect CI, search issues, ask a teammate, or message the maintainer who knows the real setup.

AI agents do not have that social fallback.

They need the repo to explain itself.

Why this breaks faster with AI agents

AI coding agents do more than read code. They choose commands, edit files, run tests, interpret failures, and decide whether a task is complete.

That means README drift becomes more expensive. If the README says one thing and CI does another, the agent has to infer which one is correct. If setup depends on an undocumented service, the agent may treat an environment failure as a code bug.

The model is not always the problem. Sometimes the repo is simply ambiguous.

That is why repo readiness for AI agents matters. The first post in this series covers the full framework. This post focuses on one specific failure mode: asking the README to carry too much operational truth.

Where README-only setup usually fails

README-only setup tends to break in a few predictable places.

1. Runtime and tool versions drift

A README might say:

install Python

But the repo may actually require Python 3.12, Poetry, Docker, and Postgres.

For a human, this becomes setup friction. For an agent, it becomes a guessing problem. The agent may choose a reasonable default that does not match the repo’s real environment.

2. Commands become outdated

Many repos start with simple commands:

npm install
npm test

Then the project grows.

CI starts using a different package manager. Tests split into unit and integration paths. The app needs a build step before verification. Some checks only run in containers.

The README may still show the old command.

An agent can run the documented command, get a passing result, and still miss the check that would fail in CI. This is the kind of drift a repo-readiness contract in Ota is meant to expose earlier, before humans or agents treat an outdated README command as the real workflow.

3. Service dependencies stay implicit

Modern repos often depend on Postgres, Redis, queues, object storage, search, or local emulators.

A README may mention these casually without explaining how to start them, which tasks require them, what ports they use, or how readiness is checked.

That creates false diagnosis.

If a backend test fails because Postgres is not running, an agent may treat the error as a code bug instead of an environment problem.

4. Safety boundaries are missing

A README often tells people how to run a repo. It rarely tells automation what not to do.

That matters because some commands are safe:

test
lint
typecheck
build

And some commands need caution:

deploy
publish
db:reset
terraform apply

The same applies to files. Source and tests may be safe to edit. Migrations, generated files, lockfiles, production config, and environment files may need review.

If these boundaries are not explicit, agents infer risk from filenames and context. That is not enough for reliable agentic development.

5. The README cannot validate itself

This is the core weakness.

A README can say pnpm test, but it does not prove the command exists.

It can say copy .env.example, but it does not prove the required variables are complete.

It can say “start Postgres before running tests,” but it does not prove Postgres is reachable.

The README can explain the project. The repo still needs a stronger way to declare, check, and run its working state.

What to do instead

You do not need to delete your README or rebuild your repo overnight.

Start by separating explanation from operational truth.

The README should become a map, not the entire operating manual.

It should still explain what the project does, who it is for, how to begin, and where contributors should go next. Then it should point readers toward clearer operational sources instead of carrying every setup detail itself.

Move operational guidance into more structured places:

CONTRIBUTING.md for contributor workflow
AGENTS.md for AI-agent guidance
.env.example for environment shape
a task runner or Makefile for common commands
CI workflows that match the documented verification path
a contract file that declares setup, tasks, execution, and safety rules

If your README currently carries everything, the first step is to move the operational burden into a smaller, more structured section or file. A lightweight manual version might look like this:

## Working with this repo

Runtime:
- Python 3.12
- Poetry
- Postgres 16

Setup:
1. Install dependencies: `poetry install`
2. Copy `.env.example` to `.env`
3. Start services: `docker compose up -d`

Verification:
- Unit tests: `poetry run pytest tests/unit`
- Full check: `poetry run pytest --cov`

Agent guidance:
- Safe to run: tests, lint, typecheck
- Do not run: deploy, publish, destructive database commands
- Do not edit: `.env`, generated files, production config

This is already better than forcing contributors or agents to guess.

But it is still prose. It can still become stale.

The next step is to make repo readiness executable, reviewable, and reusable by humans, CI, and AI agents.

Where Ota fits

This is where Ota becomes useful.

Ota does not replace the README. It removes the pressure for the README to behave like an execution system.

Ota is open repo-readiness infrastructure for humans and AI agents. Its docs describe repo readiness as the state of a repo being runnable and diagnosable, so the next safe step is obvious. It also treats ota.yaml as the repo-level source of truth for readiness, setup, execution, and safe AI-agent guidance.

Instead of asking humans, CI, and agents to reconstruct setup from scattered README prose, Ota lets the repo declare its working state in an explicit contract.

That contract can describe what the repo needs, which tools are expected, which tasks exist, how setup should happen, what is safe for agents to run, and what should be verified after changes.

The README can still explain the project.

But the contract carries the operational truth.

ota doctor checks whether the repo is ready and points to the blocker
ota validate checks whether the contract itself is valid
ota tasks shows the work the repo has declared
ota up prepares the repo from that contract

AI agents do not need more scattered hints. They need a reliable path.

The better model

The future is not README versus tools.

It is README plus explicit repo readiness.

The README remains the human-friendly front door. It explains the project, purpose, architecture, and contribution path.

Setup, execution, verification, environment requirements, and agent-safe boundaries should live in a form that can be reviewed, validated, and reused.

That is the shift:

Old model:
Read the README and figure it out.

Better model:
Read the README for context. Trust the repo contract for how work runs.

This reduces onboarding friction, narrows local versus CI drift, and helps agents avoid confident guessing.

Conclusion

READMEs are still important.

The issue is not that READMEs are bad. The issue is that many teams ask them to carry too much operational weight.

As AI agents become part of software workflows, repo ambiguity becomes harder to ignore. Agents need clear context: runtimes, services, tasks, safe commands, protected paths, and verification rules.

The better question is no longer, “Does this repo have documentation?”

It is:

Can this repo explain how it works clearly enough for a human, CI system, or AI agent to trust it?

If the answer is no, the README is not the enemy.

It is just carrying too much weight.

Continue reading

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

Originally Posted: https://ota.run/blog/why-readme-driven-infrastructure-breaks-for-ai-agents-4b2o

What Should Happen When a Repo Does Not Run?

Adamma — Fri, 22 May 2026 19:22:10 +0000

Most repos still fail in a strangely manual way.

You run a command.
It breaks.

Now you have to reverse-engineer the repo:

read the error
search the README
inspectpackage.json, Docker files, and lockfiles
compare local state with CI
ask someone who already knows
try a few fixes and hope one is the real one

That is annoying for developers, but it is a bigger problem now that AI agents are being asked to work inside unfamiliar repositories.

If an AI agent is told to fix a bug, it first needs a reliable answer to some basic operational questions:

What does this repo require to run?
Which workflow is the intended front door?
Which missing dependency is actually blocking readiness?
Which commands are safe to run?
What should stop progress vs what is only a warning?

In most repos, those answers are spread across docs, scripts, CI config, and tribal knowledge. That means the agent is not operating from repo truth. It is guessing. That is the problem ota doctor is meant to solve.
ota doctor evaluates a repo against its readiness contract, defined in ota.yaml, and reports:

whether the repo is ready
what is missing
what is blocking readiness
what is only degraded or advisory
the next safe action to take

So instead of “command failed, go investigate the repo,” you get a structured readiness diagnosis.

For maintainers, that means fewer contributors rediscovering the same setup failures from scratch.

For contributors, it means less time spent diffing docs against reality.

For AI-assisted development, it gives the agent an operational signal before it starts making changes in a repo it does not yet understand.

The broader question is simple:
When a repo is not runnable, what should it say, and how explicitly should it say it?

My view is that “good luck, read the repo” is no longer good enough.

If you want to pressure-test that idea on a real codebase, try Ota and see what ota doctor surfaces:
https://github.com/ota-run/ota

Originally Posted:https://ota.run/blog/what-should-happen-when-a-repo-does-not-run-31ai