ota

name	ota
description	Use when working on anything Ota-specific: creating, refining, reviewing, or explaining Ota contracts (`ota.yaml`), modeling execution governance for humans and AI agents, working through `ota doctor` / `ota up` / `ota run`, handling agent safety surfaces, Ota Studio boundaries, or when deciding whether a problem belongs in the repo contract or in Ota itself.

Ota

Use this skill when the task is about Ota-specific contract authoring, contract review, execution governance for humans and AI agents, or Ota platform judgment.

Do not use this skill for generic YAML generation. It is for truthful execution governance, not schema-only completion.

Core product posture

• Doctor first, contract second.
• ota.yaml is the canonical source of execution governance truth.
• Prefer one explicit operational path over parallel scripts and tribal knowledge.
• If the repo needs ugly glue because Ota lacks a product feature, call it out as an Ota gap instead of normalizing the workaround.

Architecture loop

Keep the Ota mental model in this order:

1. contract truth
2. execution truth
3. proof and receipt truth
4. semantic diff and correlation
5. policy and governance truth

Use the matching surface for the real question:

• contract truth: ota.yaml, ota.workspace.yaml, ota validate
• execution truth: ota doctor, ota up, ota run, ota tasks, ota execution plan
• proof and receipt truth: ota receipt
• semantic diff and correlation: ota diff, ota receipt --snapshot, ota receipt --json --baseline ...
• policy and governance truth: .ota/org-policy.yaml, ota policy, ota policy review

Do not collapse these into one artifact mentally or in guidance. The contract declares, execution selects, proof records, diff compares semantic truth, and policy constrains approval.

For workspace contracts, keep one more boundary explicit:

• use repos.<name>.tasks.<workspace_task>.task when one shared workspace verb should map to a different repo-local task name
• do not force mixed-name cross-repo flows back into shell wrappers just because the repos do not share one literal task name

Source priority

Prefer sources in this order:

1. the repo you are actively working on
2. local canonical Ota references, when they exist in the checkout:
   • ota.yaml
   • examples/
   • docs/spec/contract-reference.md
   • docs/spec/json-output-reference.md
   • README.md
3. public references in references/official-sources.md

When the question is specifically about archived semantic truth, semantic diff, or receipt correlation as a public operator surface, prefer the dedicated public page https://ota.run/docs/reference/semantic-snapshots-and-correlation after checking the local repo sources above.

When the question is broader than one command or one receipt and you need the public architecture loop itself, prefer https://ota.run/docs/reference/execution-governance-loop after checking the local repo sources above.

When the active repo is ota-run/ota, also prefer the local core spec docs/spec/semantic-snapshots-and-correlation.md for the shipped contract details behind:

• receipt.contract_snapshot_hash
• receipt.assumption_set_hash
• ota receipt --snapshot
• contract_changes[]
• likely_related_changes[]
• summary.comparison.correlation

Do not jump straight to public docs if the local repository already contains the canonical answer. If the active repo is not the Ota repo, treat local repo files as evidence about that project, not as Ota product documentation.

When the active repo is ota-run/ota, also inspect adjacent first-party repos when the task touches their ownership boundary:

• inspect ota-site when the task affects public install docs, public contract docs, public examples, onboarding guidance, or anything the docs site promises to operators
• inspect ota-run/skills when the task affects first-party agent-skill guidance, contract authoring behavior, or the public skill installation story

Do this only when the task really crosses that boundary. Do not turn routine Ota implementation work into a mandatory three-repo read.

Bootstrap flow

Always prefer using the real Ota binary when it is available.

1. Check whether ota exists.
2. If it is missing, ask for approval before installing it.
3. Use the official install commands only:
   • macOS / Linux:
     • curl -fsSL https://dist.ota.run/install.sh | sh
   • Windows PowerShell:
     • irm https://dist.ota.run/install.ps1 | iex
   • when teaching repo-authored bootstrap truth, prefer structured agent.bootstrap.ota.source over raw shell strings:
     • kind: version for released proof
     • kind: git_rev for deterministic unreleased proof
     • kind: branch only for active pressure testing
   • when a repo already declares agent.bootstrap.ota.source, apply the canonical mapping directly instead of guessing:
     • kind: version
       • shell: curl -fsSL https://dist.ota.run/install.sh | OTA_VERSION=<version> sh
       • PowerShell: $env:OTA_VERSION='<version>'; irm https://dist.ota.run/install.ps1 | iex
     • kind: git_rev
       • shell: curl -fsSL https://dist.ota.run/install.sh | OTA_GIT_REV=<rev> sh -s -- --from-git
       • PowerShell: $env:OTA_GIT_REV='<rev>'; & ([scriptblock]::Create((irm https://dist.ota.run/install.ps1))) -FromGit
     • kind: branch
       • shell: curl -fsSL https://dist.ota.run/install.sh | OTA_GIT_BRANCH=<branch> sh -s -- --from-git
       • PowerShell: $env:OTA_GIT_BRANCH='<branch>'; & ([scriptblock]::Create((irm https://dist.ota.run/install.ps1))) -FromGit
   • when a GitHub Actions job needs direct ota commands and the repo already declares agent.bootstrap.ota.source, prefer the first-party ota-run/setup@v1 action with source: contract over duplicating OTA_VERSION, OTA_GIT_REV, OTA_GIT_BRANCH, or --from-git in workflow YAML
   • when a repository declares contract-owned CI bootstrap or verification truth, add a dedicated pull-request gate with ota-run/action@v1, command: doctor, , and ; it fails only on Ota-established CI bootstrap or verification drift, not ordinary Doctor warnings. Keep it separate from general readiness reporting so the blocking reason stays explicit.

Prefer the official install docs and repository references in references/official-sources.md when you need canonical links.

Do not silently install Ota, install agent skills, modify shell profiles, or overwrite an existing ota.yaml. Ask first unless the user explicitly requested that action.

Canonical command workflow

Use the smallest real Ota workflow that fits the task:

• ota doctor
  • inspect readiness blockers, warnings, next actions, and agent guidance
  • use ota doctor --fix --dry-run to preview the currently shipped deterministic fix lane
  • use ota doctor --fix when the repo truth should allow safe deterministic repair such as repo-hygiene cleanup or native command-acquired tool activation; plain ota doctor should stay non-mutating
  • do not use mutating ota doctor --fix to route around replay-input admission. When an active replay-input policy is unavailable, evaluates to deny or review, or a declared hard pin is unavailable or mismatched, Ota refuses before repo-hygiene or tool-activation mutation. ota doctor --fix --dry-run remains a non-mutating preview
• ota init
  • create a starter contract only when the user wants Ota adoption or no contract exists
  • prefer the emitted starter shapes Ota now owns directly: toolchains.*, prepare.kind: dependency_hydration for setup, and command for simple finite task bodies
• ota detect
  • inspect deterministic repo evidence before broadening a contract
  • treat ota detect --write as the conservative first-write lane, not the full starter lane
  • when reviewing a detect-written contract, read metadata.ota.detect.field_ownership together with metadata.ota.detect.field_admission so direct detector-owned writes are not confused with conservative starter-policy promotions
  • for AGENTS.md / CLAUDE.md pressure, keep the boundary explicit: structured external boundary lists may be admitted as detect evidence, narrow labeled command sections and bounded structured command tables inside those command sections may be admitted as low-authority task guidance, including exact | Task | Command | and adjacent | Command | description | forms under headings such as Commands, Individual Commands, Common Commands, Quick Reference Commands, Build/Test Commands, and Build & Development Commands when ota can still recover a stable canonical task name from the command itself or from a bounded task label such as , , or ; placeholder-heavy command templates like , , or obvious scaffolding should stay ignored because they are guidance, not runnable task truth; prose should stay ignored, and Ota-generated agent docs from should be treated as self-origin guidance and excluded from detect evidence, including older generated docs that only say ./ota.yaml`.by ota agents` marker

If a contract already exists, start with ota doctor and ota validate before editing it.

If the repository has no contract yet:

1. inspect the smallest real operational surface
2. model the minimum truthful contract
3. validate it
4. only then broaden the contract if real repo truth requires it

For agent, Studio, CI, or other integration surfaces, prefer Ota JSON output (--json) or documented schemas. Do not parse rich human output unless no machine-readable surface exists, and call that out as an Ota platform gap. When reading receipt/proof machine output, prefer explicit stage ownership over inferring from labels:

• receipt.steps[*].stage_family carries the broad governance family
• ota proof runtime --json carries stage_family: "proof" alongside the finer proof phase
• ok is execution/readiness success only. It is necessary but insufficient for proof breadth; consumers must read proof_verdict with not_proved[].
• use ota proof runtime --json --archive when a runtime proof must later support a governance claim. Then read ota doctor --json claim_assurance[]: proof breadth is supported only by a content-addressed witness archive matching current semantic contract, clean source identity, and resolved execution scope; a matching failed proof is contradicted and stale evidence is unknown.
• use ota proof lifecycle --workflow <name> --json --archive only for a workflow that declares proof.lifecycle over manager-owned services. The runner first executes the normal workflow prerequisite closure, then either leases manager-observed inactive services or creates one transaction-bound ephemeral container session for a declared boundary_terminated service. It starts and readies the dependency closure, optionally runs one finite assertion, then finalizes in reverse order even after a failed start, readiness failure, assertion failure, or interrupted child. When declared, the typed assertion record carries the terminal task state, exit code, and bounded runner-captured output tails for diagnosis; it does not turn that output into broader application proof. A manager-reported pre-existing or unknown-state service is never stopped. The archive is local, content-addressed evidence bound to the semantic contract snapshot, selected scope, transaction, service records, and terminal verdict; it does not support claim assurance, CI projection, or a broader runtime/application proof.
• lifecycle proof reuses selected-workflow --agent, --mode, and --member admission. The selected mode applies to prerequisite and assertion tasks. Replay-input admission evaluates the exact workflow prerequisite-plus-assertion closure before any lifecycle task, service transition, or assertion starts. Runtime proof similarly includes its post-readiness seam observers and selected negative-control task, then admits before creating .ota/proof artifacts or spawning its child runtime. A refused machine result carries execution_started: false with the hard-pin and active policy evidence. A boundary_terminated service requires structured / commands and resolving to an ephemeral context; Ota runs those commands inside its session and attests removal of that exact session. Machine consumers must require the same in archive scope and every isolated service record. A failed removal is attested as incomplete cleanup, never promoted to , host-manager inactivity, or application output. Native generic host start/stop remains ineligible until it has a typed state observer.

Contract authoring workflow

When creating or refining a contract:

1. Identify the real operational truth with the minimum repo reading needed:
   • setup path
   • runtime dependencies
   • env sources and required vars
   • service and readiness ownership
   • canonical tasks
   • agent-safe boundaries
2. Model only what is actually true today.
3. Keep the contract minimal but complete enough that:
   • ota doctor is useful
   • ota up has a clear path
   • ota run executes named tasks honestly
4. Prefer contract fields over repo-local helper scripts when Ota already supports the behavior cleanly.

Prefer these concrete shapes when repo truth matches them:

• use aggregate for finite task grouping instead of fake run: "true" bodies
• use command.cwd when the task truth is still one finite executable plus stable argv but it should run from a repo subdirectory instead of hiding cd ... && ... in shell
• use launch.kind: command for long-running service processes instead of opaque run
• when a supported long-running server adapter would otherwise duplicate bind flags already owned by explicit runtime.listeners, use launch.runtime_projection so ota projects bind argv from canonical runtime listener truth instead of repeating --host / --port, -b / -p, or Next.js --hostname / --port in launch.args; use the nextjs adapter with a direct structured next dev invocation rather than a package-script wrapper that owns those flags
• use tasks.<name>.compose when the repo truth is a finite docker|podman compose lane ota should own directly, whether that is an in-service exec/run/attach command or a staged compose up, compose build, compose restart, compose rm, compose logs, or project-scoped compose down task; use omitted compose.engine to use the default Docker Compose CLI, or set compose.engine: podman when the same body should execute through Podman Compose; use compose.detach: true only with compose.kind: exec or compose.kind: up, keep compose.rm: true only with compose.kind: run, keep compose.build: true only with compose.kind: run for one-off service shells that must rebuild the selected service image before execution, keep compose.service_ports: true only with compose.kind: run for one-off service shells that must publish the service's declared ports, keep compose.force_recreate: true only with compose.kind: up, keep only with , keep only with , keep only with for , keep only with for , keep for //, and use for staged , , , , , , or

Before editing:

• preserve existing user intent in ota.yaml
• make the narrowest complete contract change
• update docs/tests only when command behavior, schema shape, or published examples change
• validate with ota validate and, when useful, ota doctor

Author from evidence, not vibes. Before writing or broadening a contract, inspect the smallest set of repo files that reveal real behavior:

• package/build manifests (package.json, workspace files, lockfiles, language manifests)
• contributor docs (README, CONTRIBUTING, DEVELOPERS, setup docs)
• CI workflows that show canonical install, build, test, and smoke paths
• compose/container files only when the workflow actually needs services or containers
• existing scripts that users already run successfully

Keep scope honest. If the contract only models one slice of a large repo, say that in project.description, workflow descriptions, and the final response. Do not make a partial contract sound like full production readiness.

Default modeling areas:

• project
• execution.contexts
• toolchains, runtimes, and tools
• env.sources and env.vars
• services and readiness
• tasks
• workflows
• checks
• agent

When deciding where something belongs, prefer:

• toolchains for managed ecosystem ownership such as Node/Corepack/pnpm or Rust/rustup
• runtimes for direct runtime presence/version checks not owned by a toolchain
• tools for standalone command checks not owned by a toolchain
• env for runtime config truth
• services for declared managed services and readiness ownership
• checks for operator-facing blockers and warnings
• tasks for named execution paths
• workflows for canonical user-facing paths through prepare/setup/run/readiness
• agent for safety and automation boundaries

Do not duplicate ownership across toolchains, runtimes, and tools. If a package manager, runtime, or command is owned by a declared toolchain, task requirements may select it, but top-level runtime/tool ownership should not be duplicated.

Requirements should live at the narrowest truthful owner.

• use context-level requirements only when every task in that context genuinely needs them
• prefer task-level requirements for most tool/runtime ownership
• keep pure action.kind:*, file-prep, env-prep, and other deterministic non-runtime tasks free of heavyweight inherited requirements unless they actually execute that tool
• when a file action, env action, or other finite host prep lane fails only because a context inherited Docker, Node, Python, or another heavyweight tool, treat that as a contract issue first and tighten the owner boundary before changing the workflow

Preferred modern contract shapes

When the repo truth supports them, push toward these shapes explicitly:

• finite verification grouping:

  • aggregate.tasks for verify, ci, and other bounded parent tasks

• long-running services:

  • launch.kind: command plus runtime.kind: service and surfaced readiness

• package-manager truth:

  • Node package managers under toolchains.node.package_managers
  • Composer-backed PHP dependency hydration through prepare.source.kind: composer
  • uv under toolchains.python.package_managers.uv when uv owns Python dependency setup/run
  • uv-backed Python dependency hydration through prepare.source.kind: uv
  • Poetry under toolchains.python.package_managers.poetry
  • Bundler under toolchains.ruby.package_managers.bundler

• deterministic setup:

  • prepare.kind: dependency_hydration instead of ad hoc install shell bodies where Ota already owns the manager lane
  • prepare.kind: sequence when one setup task must compose multiple structural finite steps
  • action.kind: ensure_container_network when shared external Docker network ownership belongs to one finite standalone setup task
  • action.kind: reset_compose_service_volume when one destructive local reset lane owns one Compose-managed service volume reset and restart sequence

• env and compose truth:

  • env.sources, env.vars, env_files, ensure_env_file, workflow-owned env rendering, and adapter_inputs.overlays.compose.env_files / adapter_inputs.overlays.bake.files for adapter-owned input truth before resorting to inline shell glue
  • OTA_HOST_WORKSPACE, OTA_HOST_UID, and OTA_HOST_GID when a native or compose task truthfully needs the real host repo path or Unix user/group ids for deterministic env interpolation; do not fall back to shell pwd, id -u, or id -g glue when ota already owns that lane
  • adapter_inputs.overlays.compose.cwd / when compose or Bake truth lives in a repo subdirectory and the task would otherwise need shell or glue

Prefer the strongest truthful contract surface, not the broadest valid YAML surface.

When the contract could be modeled more than one way, choose by owner boundary:

• use prepare.kind: sequence when the lane is still structural setup such as dependency or image hydration and those steps share one honest setup owner
• use action.kind: ensure_bundle when the lane is deterministic setup built from action primitives such as env/file prep plus shared Docker network bootstrap
• use action.kind: ensure_git_checkout when the lane is deterministic repo-local Git materialization, including optional declared remote reconciliation, and should stay on the same governed setup surface as file/env prep instead of shell bootstrap glue
• use action.kind: ensure_container_network when the lane is deterministic external Docker network bootstrap and should stay machine-readable as its own setup lane
• use action.kind: reset_compose_service_volume when the lane is a destructive local Compose-managed service-data reset and should stay explicit instead of disappearing into shell
• use workflows.<name>.prepare.task when that bootstrap step deserves reuse or its own task identity; use workflows.<name>.prepare.action when the workflow itself owns it directly
• keep steps as separate finite tasks when they need distinct reuse, separate requirements/effects, or independent operator entrypoints

For fuller holistic shapes, also use:

• references/workflow-service-patterns.md for workflows, services, env modeling, requires_services, context-bound execution, and post-run hooks
• references/agent-and-governance-checklist.md for agent, checks, effects, proof posture, and CI/version-floor governance
• references/execution-governance-capability-map.md when you need the dedicated public reference, evidence boundary, and copy-ready example for safe execution, CI projection, sandboxing, proof, replay, claim assurance, crossings, or semantic snapshots
• references/pressure-testing-protocol.md before selecting, modeling, or declaring a pressure repo complete; it defines the required proof matrix, Ota-gap review, and first-party propagation decision
• the public examples repo when a compact copy-ready surface is better than prose alone: reference/bake-adapter-inputs, reference/action-ensure-env-file, reference/action-ensure-bundle, reference/action-ensure-git-checkout, reference/action-ensure-container-network, and reference/compose-adapter-inputs

Known regression traps

Watch for the concrete regressions we have repeatedly seen in pressure-test repos:

• runtime.kind: service paired with opaque run instead of launch.kind: command
• supported server launch adapters still duplicating bind flags in launch.args even though explicit runtime.listeners already own the canonical bind host/port and launch.runtime_projection should carry the translation
• fake aggregate bodies such as run: "true" where aggregate should own the task shape
• aggregate membership smuggled through depends_on instead of aggregate.tasks
• Poetry declared under tools.poetry when it actually owns Python dependency truth
• mixed-ecosystem setup script bodies where prepare.kind: sequence should own the lane instead
• raw uv sync or uv pip install -r ... setup bodies in Python repos where first-class prepare.source.kind: uv now exists
• raw npm install or non-lockfile setup when the repo truth is npm plus package-lock.json
• invalid generic native package fields where explicit manager-owned package fields should own fulfillment or policy truth
• public CI or proof workflows pinned to an older Ota build than the contract surface they execute
• env-file ownership baked into shell commands when first-class env surfaces can own that truth
• compose interpolation files modeled as process env_files instead of tasks.<name>.adapter_inputs.overlays.compose.env_files
• compose or Bake subdirectory truth still buried in shell cd ... && docker ... glue or docker compose --project-directory ... instead of adapter_inputs.overlays.compose.cwd or adapter_inputs.overlays.bake.cwd
• fake host alias tasks such as typecheck:host or build:host where one task identity plus execution.modes.<mode>.depends_on should own the plane-specific prerequisite truth
• Bake file selection buried in shell docker buildx bake -f ... flags instead of tasks.<name>.adapter_inputs.overlays.bake.files or workflows.<name>.adapter_inputs.overlays.bake.files
• missing metadata.ota.minimum_version on any contract, especially a published example; a contract that uses newer Ota parsing or runtime behavior must not rely on an implicit version floor

Production-readiness gates

When the user asks whether an Ota contract is solid, production-ready, PR-ready, or suitable for a serious OSS repo, evaluate these gates explicitly:

• Scope honesty: the contract description and workflow names match the repo slice actually modeled.
• Deterministic setup: CI/proof install paths use lockfile-respecting commands where the repo supports them.
• Bounded agent defaults: agent.default_task, agent.safe_tasks, and verify_after_changes prefer finite verification tasks over long-running dev loops.
• Refusal controls: when a repo has an unsafe publish, deploy, or release lane, declare it under agent.refusal_canaries and prove the real runner boundary with ota run --agent --expect-refusal <task> or ota up --agent --expect-refusal --workflow <workflow>. Do not model this as a shell test or declare an expected reason: Ota must derive the refusal from the current closure.