Skip to content

ADR 0005 — EXPRESSION-PROFILE-REGISTRY lands in v1.5, not v1.0

Status: Accepted Date: 2026-05-25 Deciders: principal-architect (eric) Supersedes: PRD §9 open question "Should we adopt EXPRESSION-PROFILE-REGISTRY runtime in v1.0 or v1.5?"

Context

The framework declares per-project profiles (micro/mini/startup/enterprise/healthcare) in PROFILE_THRESHOLDS (src/pipeline/gates.py). The question was whether each agent should also carry an expression profile — per-agent personality/style parameters (formality, verbosity, default examples, default tone) — and whether to ship that runtime at v1.0 or defer.

At v1.0 / v1.1: - Project-level profiles work and gate contextual rules (Rules 3, 18, etc.) - AdaptiveThresholds (Sessão #6) adjusts those at runtime per SystemPressure - Agent prompts in _agents-registry.yaml are static (no expression overlay)

The case for v1.0: - Agents respond inconsistently across tone/length/formality without explicit control - Multi-agent teams need a way to differentiate "warm onboarding bot" from "terse security auditor"

The case for v1.5+: - Opus 4.7 (Sessão #4) calibrates response length to task complexity already - Adding expression overlay before observing real production traffic risks premature commitment to the wrong parameter set - The framework's first job is to generate real outputs and measure their variance — Expression Profile then layers on data, not theory

Decision

Defer to v1.5. v1.x ships without EXPRESSION-PROFILE-REGISTRY.

Project-level profiles + AdaptiveThresholds + system-prompt steering at the specialist level cover 80% of what Expression Profile would add, without the commitment cost.

At v1.5, design Expression Profile against accumulated AgentMetrics data (formality variance, verbosity P50/P95, etc.) — that's data we don't yet have at v1.0.

Consequences

Positive

  • No premature parameter explosion in _agents-registry.yaml
  • Decision is data-informed, not theory-informed
  • v1.x release surface is smaller / more focused

Negative

  • Inconsistent agent voice across sessions until v1.5
  • Workaround needed for the "warm vs terse" use case (system prompt customization at orchestrator level)

Risks + mitigations

  • R: users hit the inconsistency and bail before v1.5 → M: ADR-documented workaround using per-orchestrator system prompts; document in CONTRIBUTING
  • R: by v1.5 the registry schema is too entrenched to add cleanly → M: reserve metadata.expression_profile_id in _agents-registry.yaml now as a schema slot

Schema reservation

Adding to _agents-registry.yaml schema (no-op for v1.x):

<agent-id>:
  layer: 4
  # ... existing fields ...
  metadata:
    expression_profile_id: null   # v1.5: references EXPRESSION-PROFILE-REGISTRY entry

Open follow-ups

  • v1.5 design session: gather 60+ days of AgentMetrics data first
  • v1.5 ADR: actual Expression Profile schema, drawn from observed variance buckets

References