# ota Workspace Reference This document describes the current `ota.workspace.yaml` contract accepted by the shipped workspace validator. For machine-readable workspace contract publication, use [`json-schemas/workspace-contract.json`](json-schemas/workspace-contract.json) locally or `https://dist.ota.run/spec/json-schemas/latest/workspace-contract.json` in CI, editors, and other tooling. ## Purpose `ota.workspace.yaml` is the canonical workspace bootstrap contract. It is separate from `ota.yaml`, which remains the canonical repo readiness contract. ## Minimal contract ```yaml version: 1 workspace: name: ota-dev git_base: https://github.com/ota repos: web: path: apps/web source: repo: web ``` ## Top-level fields - `version`: required, currently only `1` - `workspace`: required workspace metadata - `repos`: required map of repo entries - `policies`: optional workspace-local policy overlays and additive governance data ## `workspace` ```yaml workspace: name: ota-dev description: Local multi-repo development workspace policy: .ota/org-policy.yaml ``` Fields: - `name`: required, non-empty string - `description`: optional string - `git_base`: optional clone base used by `repos..source.repo` - `policy`: optional policy pack path or HTTP(S) URL resolved from the workspace root ## `repos` ```yaml repos: web: path: apps/web tasks: prepare-dev: task: build-sdk source: repo: web api: path: services/api contract: services/api/ota.yaml required: true depends_on: - web source: git: https://github.com/ota/api.git ref: main ``` Fields: - `path`: required path to a repo directory, relative to `ota.workspace.yaml` - `contract`: optional explicit repo contract path, relative to `ota.workspace.yaml` - `workflow`: optional repo workflow selection used by workspace execution paths - `tasks`: optional workspace-owned task bindings that map one shared workspace task name to a repo-local task name - `required`: optional boolean - `depends_on`: optional list of workspace repo names - `source`: optional acquisition source for repos that are not present yet `tasks` fields: - `tasks..task`: required repo-local task name `ota workspace run ` should execute for this repo `source` fields: - `git`: explicit clone URL or git-accepted clone source - `repo`: repo path or slug resolved against `workspace.git_base` - `ref`: optional branch, tag, or ref to checkout after clone Design intent: - `repos..tasks` lets one workspace verb span repos that do not share the same local task name - this keeps cross-repo execution truth in the workspace contract instead of hiding it in shell wrappers or repo-specific readme steps - ota still falls back to the literal task name when no workspace binding is declared for that repo - `source.git` is the canonical acquisition field - `source.repo` is shorthand for multiple repos sharing the same `workspace.git_base` - both are generic git concepts and work for GitHub, GitLab, Bitbucket, and internal git hosts Current validation behavior: - repo names must not be empty - workspace must declare at least one repo - repo `path` must be non-empty - repo `path` must exist and point to a directory unless `source` is declared - `contract` must be non-empty when present - `tasks` binding names must not be empty - `tasks..task` must not be empty - if `contract` is omitted, ota expects `/ota.yaml` - `source` must declare exactly one of `git` or `repo` - `source.repo` requires `workspace.git_base` - `depends_on` references must resolve to known workspace repos - workspace repo dependency cycles are rejected - each present repo contract must load and pass repo-level validation - when the repo is already present and its contract validates, each `tasks` binding target must resolve to a non-internal repo task - when the repo is already present and its contract validates, a workspace task binding must not shadow a visible repo task of the same name with a different target task, because `ota workspace run ` would become ambiguous ## Current scope The shipped workspace surface is intentionally narrow: - workspace contract parsing - workspace contract validation - repo contract validation through the workspace contract - workspace-level diagnosis as orchestration over repo-level `doctor` - workspace-level prepare flow as orchestration over repo-level `up` - acquisition of missing repos before workspace prepare Current non-goals: - workspace task orchestration beyond one shared workspace task name mapped repo-by-repo - workspace-wide environment mutation - hidden repo bootstrap behavior - passing a repo URL directly on the CLI without a workspace contract - GitHub API integration or non-git acquisition modes ## `ota workspace doctor` Current workspace diagnosis behavior: - validates workspace structure first - evaluates repos in dependency order - can diagnose independent repos concurrently when `--jobs` is greater than `1` - preserves deterministic repo ordering in the final report - diagnoses each referenced repo through its own `ota.yaml` - reports missing-but-acquirable repos as not yet acquired instead of treating them as unreadable local paths - preserves repo-level diagnosis semantics for required repos - downgrades optional repo errors to warnings at the workspace layer - rejects required repos that depend on optional repos - `ota workspace doctor --json` and `ota workspace check --json` both publish workspace roll-up `verdict` / `agent_verdict`, additive workspace `summary.primary_blocker`, and per-repo `primary_blocker`; additive blocker `code` only appears when the blocker came from explicit stable finding identity This keeps workspace behavior as orchestration over repo readiness, not a parallel readiness system. ## `ota workspace tasks` and `ota workspace run` Current workspace task behavior: - `ota workspace tasks` lists visible repo tasks in dependency order - it also lists workspace-owned task bindings when `repos..tasks` maps a shared workspace task name to a different local repo task - `ota workspace run ` executes the same literal repo task name by default - when `repos..tasks..task` is declared, `ota workspace run ` resolves that repo-local task instead for that repo - workspace run receipts and JSON output keep the requested workspace task visible and also expose the resolved repo task when the binding differs ## `ota workspace up` Current workspace prepare behavior: - validates workspace structure first - acquires missing repos declared with `source` before repo-level bootstrap - runs repo-level `up` for each referenced repo - can prepare independent repos concurrently when `--jobs` is greater than `1` - respects declared workspace repo dependency order - blocks downstream repos when a dependency does not become ready - aggregates repo-level status, phase, findings, and exit details - captures repo child stdout and stderr per repo so the final report remains deterministic - emits live repo progress on stderr in text mode so users can see execution moving without losing ordered final output - optional repo failures do not fail the overall workspace status - `--stream` opts into raw live child process output instead of buffered per-repo output Current execution policy: - workspace repo execution defaults to sequential because `--jobs` defaults to `1` - ota only parallelizes repos whose dependencies are already satisfied - final reporting remains in deterministic repo order even when execution is concurrent - required repos must not depend on optional repos, because required readiness cannot rest on optional guarantees - `--stream` is currently text-only and requires `--jobs 1` so raw child logs do not interleave Current non-goals: - cross-repo dependency scheduling - passing a repo URL directly on the CLI without a workspace contract - host or workstation provisioning - a workspace-only bootstrap engine that bypasses repo contracts - implicit pull, fetch, or update behavior for repos that already exist locally - GitHub API integration or non-git acquisition modes ## `ota workspace refresh` Current workspace refresh behavior: - validates workspace structure first - refreshes repos that already exist locally and have a declared source - leaves missing repos alone so `ota workspace up` remains the bootstrap path - can refresh independent repos concurrently when `--jobs` is greater than `1` - respects declared workspace repo dependency order - blocks downstream repos when a dependency does not become ready - aggregates repo-level status, phase, findings, and exit details - captures repo child stdout and stderr per repo so the final report remains deterministic - emits live repo progress on stderr in text mode so users can see execution moving without losing ordered final output - optional repo failures do not fail the overall workspace status - `--stream` opts into raw live child process output instead of buffered per-repo output - `--dry-run` previews the refresh commands without changing repo state - `--force` force-fetches and hard-resets refreshed repos to the declared source or `--ref` override - `--prune` prunes stale remote-tracking refs during refresh - `--ref ` overrides the source ref used for refresh Current execution policy: - workspace repo execution defaults to sequential because `--jobs` defaults to `1` - ota only parallelizes repos whose dependencies are already satisfied - final reporting remains in deterministic repo order even when execution is concurrent - required repos must not depend on optional repos, because required readiness cannot rest on optional guarantees - `--stream` is currently text-only and requires `--jobs 1` so raw child logs do not interleave Current non-goals: - cloning missing repos ## `ota workspace diff` Current workspace diff behavior: - validates workspace structure first - reads the current local git state for each acquired repo without mutating anything - compares each repo against its declared source ref when present, or upstream branch when the source ref is not pinned - reports `MATCH` when the repo is clean and aligned, `DIRTY` when the worktree has local changes, `DIFFERENT` when commit counts differ, `MISSING` when the repo is absent, and `UNRESOLVED` when git state cannot be compared safely - can compare independent repos concurrently when `--jobs` is greater than `1` - never clones, fetches, resets, or writes repo state - differences are surfaced in the report but do not fail the command Current non-goals: - refreshing or mutating repo state - cloning missing repos automatically - cross-repo dependency scheduling - passing a repo URL directly on the CLI without a workspace contract - host or workstation provisioning - a workspace-only bootstrap engine that bypasses repo contracts - implicit pull, fetch, or update behavior for repos that already exist locally - GitHub API integration or non-git acquisition modes ## `ota workspace status` Current workspace status behavior: - validates workspace structure first - reads readiness and local git drift for each workspace repo without mutating anything - reports readiness and drift together in one operational summary - can compare independent repos concurrently when `--jobs` is greater than `1` - never clones, fetches, resets, or writes repo state - readiness findings and drift findings are surfaced in the same report - `--json` reports the combined roll-up with `mode: "status"` Current execution policy: - workspace repo execution defaults to sequential because `--jobs` defaults to `1` - ota only parallelizes repos whose dependencies are already satisfied - final reporting remains in deterministic repo order even when execution is concurrent - required repos must not depend on optional repos, because required readiness cannot rest on optional guarantees Current non-goals: - mutating repo state - cloning missing repos automatically - cross-repo dependency scheduling - passing a repo URL directly on the CLI without a workspace contract - host or workstation provisioning - a workspace-only bootstrap engine that bypasses repo contracts - GitHub API integration or non-git acquisition modes ## `ota workspace receipt` Read-only workspace receipts capture the current workspace state as an execution artifact. Current behavior: - validates workspace structure first - reads readiness and local git drift for each workspace repo without mutating anything - records the combined workspace state as a receipt with one step per repo - can compare independent repos concurrently when `--jobs` is greater than `1` - never clones, fetches, resets, or writes repo state - `--json` reports the receipt roll-up with `mode: "receipt"` - the receipt records the same readiness, drift, and findings scan so CI or agents can archive it deterministically Current non-goals: - mutating repo state - cloning missing repos automatically - cross-repo dependency scheduling - passing a repo URL directly on the CLI without a workspace contract - host or workstation provisioning - a workspace-only bootstrap engine that bypasses repo contracts - GitHub API integration or non-git acquisition modes