Agent OS: unify profile taxonomy and config contract

[Q00]

Context

The current Agent OS PR stack is using the word profile for several different concepts:

• feat(orchestrator): Agent OS runtime_profile (Codex backend, supersedes #488) #505 uses orchestrator.runtime_profile as a Codex backend profile selector, e.g. worker -> --profile ouroboros-worker.
• feat(orchestrator): Stage enum + runtime_profile.stages config (slice 1 of #519) #538 / Stage-Runtime mapping — runtime_profile.{interview,execute,evaluate,reflect} #519 use orchestrator.runtime_profile as a stage-to-runtime routing object, e.g. interview -> codex, evaluate -> claude_code.
• Add provider-neutral task profiles for Codex-backed Ouroboros work #570 introduces provider-neutral task/LLM profiles and maps them to backend-native anchors such as Codex --profile.

Each individual concept is useful, but the public config vocabulary is currently overloaded. This creates stack-level conflict: two PRs can both be correct locally while still assigning incompatible meanings to the same key.

This issue should lock the Agent OS profile taxonomy before more runtime/profile PRs harden around incompatible names.

Problem

profile currently means at least four things:

1. Runtime backend — the concrete harness/process used for a stage, e.g. claude, codex, opencode, hermes, gemini.
2. Stage runtime routing — which runtime backend serves interview, execute, evaluate, reflect, etc.
3. Provider-neutral LLM/task profile — an Ouroboros-level profile such as fast, standard, deep, frontier that can specify model, turn budget, reasoning effort, temperature, and provider-specific mappings.
4. Backend-native profile — a provider/harness-owned anchor such as Codex CLI --profile ouroboros-standard.

When these are all called runtime_profile, users and maintainers cannot tell whether a config block selects a runtime, selects a model profile, or maps to a backend-native profile.

Proposed vocabulary

Recommended naming, subject to maintainer revision:

Concept	Proposed name	Example
Concrete harness/backend	runtime_backend	codex, opencode, claude_code
Stage -> runtime binding	stage_runtime or runtime_routing	interview: codex, evaluate: claude_code
Provider-neutral LLM/task profile	llm_profile / task_profile	fast, standard, deep, frontier
Role -> LLM/task profile binding	llm_role_profiles	qa: frontier, reflect: deep
Backend-native profile anchor	provider_profile / codex_profile	codex: ouroboros-frontier
Legacy Codex worker profile from #505	codex_profile or migrated into llm_profiles	ouroboros-worker

The important invariant is not the exact spelling above. The invariant is: one public config key must have one semantic meaning.

Candidate config shape

One possible shape:

orchestrator:
  runtime_backend: claude
  stage_runtime:
    default: claude
    stages:
      interview: codex
      execute: opencode
      evaluate: claude_code
      reflect: hermes

llm_profiles:
  fast:
    max_turns: 1
    temperature: 0.0
    provider_profiles:
      codex: ouroboros-fast
  standard:
    max_turns: 3
    provider_profiles:
      codex: ouroboros-standard
  deep:
    max_turns: 8
    provider_profiles:
      codex: ouroboros-deep
  frontier:
    max_turns: 12
    provider_profiles:
      codex: ouroboros-frontier

llm_role_profiles:
  interview: deep
  implementation: standard
  evaluation: deep
  qa: frontier
  reflect: deep

Alternative shapes are fine if they preserve the separation between stage routing, LLM/task profile selection, and backend-native profile anchors.

Backward compatibility requirements

• Existing orchestrator.runtime_backend behavior must remain valid.
• Existing feat(orchestrator): Agent OS runtime_profile (Codex backend, supersedes #488) #505-style orchestrator.runtime_profile: worker installs need an explicit migration path or compatibility shim.
• Stage-Runtime mapping — runtime_profile.{interview,execute,evaluate,reflect} #519 stage routing should not reuse the same scalar field if that field already means a backend-native profile.
• Add provider-neutral task profiles for Codex-backed Ouroboros work #570 provider-neutral profiles should not be confused with process/runtime stage routing.
• Setup must not overwrite existing explicit model/profile choices without a clear compatibility rule.

Acceptance criteria

• A terminology table is added to the Agent OS docs, linked from the existing docs(agent-os): lock kernel terminology #557 terminology reference.
• The final config keys distinguish runtime routing, LLM/task profiles, and backend-native profiles.
• feat(orchestrator): Agent OS runtime_profile (Codex backend, supersedes #488) #505, feat(orchestrator): Stage enum + runtime_profile.stages config (slice 1 of #519) #538/Stage-Runtime mapping — runtime_profile.{interview,execute,evaluate,reflect} #519, and Add provider-neutral task profiles for Codex-backed Ouroboros work #570 can be reconciled without assigning two meanings to orchestrator.runtime_profile.
• Config loader tests cover legacy profile migration or rejection with an actionable error.
• Setup tests cover preservation of existing user profile/model configuration.
• Runtime/provider tests prove the selected stage runtime and selected LLM profile are resolved independently.

References

• [RFC] Agent OS runtime contract: capabilities, policy, directives, and replayable agent processes #476 Agent OS runtime contract
• feat(orchestrator): Agent OS runtime_profile (Codex backend, supersedes #488) #505 Agent OS runtime_profile for Codex backend
• Stage-Runtime mapping — runtime_profile.{interview,execute,evaluate,reflect} #519 Stage-Runtime mapping
• feat(orchestrator): Stage enum + runtime_profile.stages config (slice 1 of #519) #538 Stage enum + runtime_profile.stages
• Add provider-neutral task profiles for Codex-backed Ouroboros work #570 Provider-neutral task profiles
• docs(agent-os): lock kernel terminology #557 Agent OS kernel terminology

[ouroboros-agent]

This looks like a multi-PR effort that needs design discussion before implementation. Labeling needs-design for human planning.

Scope assessment:

• Affects public config vocabulary and schema boundaries in src/ouroboros/config/models.py and src/ouroboros/config/loader.py.
• Requires compatibility and migration decisions for existing config/setup behavior, plus coverage across setup/config tests and runtime/provider resolution tests.
• Reconciliation spans multiple existing issue/PR threads (feat(orchestrator): Agent OS runtime_profile (Codex backend, supersedes #488) #505, Stage-Runtime mapping — runtime_profile.{interview,execute,evaluate,reflect} #519, feat(orchestrator): Stage enum + runtime_profile.stages config (slice 1 of #519) #538, Add provider-neutral task profiles for Codex-backed Ouroboros work #570) rather than a single isolated implementation change.

Suggested approach:

• Lock the terminology and ownership of each config key first.
• Define the migration/compatibility contract for legacy runtime_profile usage.
• Split follow-up implementation into scoped PRs for schema/loader changes, setup behavior, docs, and runtime/provider tests.

ouroboros-agent[bot]