Typical signals

execution preferences are explicit
env rules are part of the contract
checks, agent guidance, and metadata are all visible

Why it matters

it turns a repo pattern into something humans, CI, and agents can read the same way
it makes the next command obvious instead of implied by README drift
it keeps readiness, setup, and execution explainable in receipts and diagnostics

Example contract

This example shows the broadest repo-local contract shape in one place so teams can see how the pieces fit together.

ota.yamlyaml

version: 1project:  name: full-contract  description: Full example of the current ota contract surface  type: applicationexecution:  preferred: native  supported:    - nativeruntimes:  node:    version: "22"    provider: volta  python: ">=3.12"tools:  pnpm:    version: "10"    required: true  uv: 0.6.0env:  vars:    OTA_ENV:      required: true      allowed:        - local        - ci    OTA_LOG_LEVEL:      default: info      allowed:        - debug        - info        - warn    PATH:      prepend:        - ./node_modules/.bin  sources:    - kind: dotenv      path: .env.local    - kind: dotenv      path: .envtasks:  setup:    internal: true    description: Install project dependencies    category: setup    script: |      pnpm install      pnpm exec prisma generate      pnpm exec playwright install --with-deps    safe_for_agent: true  lint:    description: Run lint checks    category: test    run: pnpm lint    depends_on:      - setup    safe_for_agent: true  dev:    description: Start the local development server    category: dev    run: pnpm dev    depends_on:      - setup  test:    description: Run the validation suite    category: test    variants:      - when:          os: linux        script: |          set -euo pipefail          export NODE_ENV=test          mkdir -p .tmp/test-logs          pnpm install --frozen-lockfile          pnpm lint          pnpm test -- --runInBand          pnpm exec playwright test --project=chromium      - when:          os: macos        script: |          set -eu          export NODE_ENV=test          mkdir -p .tmp/test-logs          pnpm install --frozen-lockfile          pnpm lint          pnpm test -- --runInBand          pnpm exec playwright test --project=webkit      - when:          os: windows        command:          exe: pnpm          args:            - test    depends_on:      - setup    safe_for_agent: truechecks:  - name: repo-config-valid    kind: precondition    severity: error    run: ./scripts/validate-config.sh    timeout: 10  - name: repo-tests    kind: health    severity: warn    run: pnpm test -- --runInBandagent:  entrypoint: setup  default_task: test  safe_tasks:    - setup    - test  verify_after_changes:    - test  writable_paths:    - src    - docs  protected_paths:    - ota.yaml    - Cargo.lock    - LICENSE  notes: |    Use `ota validate` before execution and `ota doctor` after contract changes.    Use `ota run test` to keep the contract and the implementation aligned.metadata:  owner: ota  team: platform