Independent public draft · format 0.1

Control how every agent communicates.

VOICE.md makes observable interaction behavior portable across models, harnesses, applications, audiences, and spoken surfaces.

Create a VOICE.md Read the specification
  • Draft 0.1.0-draft.2
  • License Apache 2.0
  • Runtime provider-neutral

Why another file?

Communication behavior is configuration.

System prompts bury voice rules inside provider-specific integration code. VoiceMD makes the contract discoverable, reviewable, compilable, and testable.

01

Portable

One local contract can compile into plain prompts, compact prompts, JSON, or ASCII-safe runtime instructions.

02

Observable

Specify openings, structure, lexicon, uncertainty, disagreement, formatting, and spoken behavior—not vague personality adjectives.

03

Testable

Deterministic lint rules and inline evaluation cases turn reviewed communication decisions into executable checks.

Hard authority boundary

Voice shapes expression. Never authority.

A runtime must reject voice instructions that cross this line, even when the contract declares otherwise.

VOICE.md may control

  • Tone and register
  • Vocabulary and formatting
  • Response structure and verbosity
  • Uncertainty and correction behavior
  • Disagreement and clarification
  • Spoken delivery constraints

VOICE.md must never control

  • Facts or source truth
  • Safety, legal, or compliance policy
  • Permissions or approval requirements
  • Tools, parameters, or side effects
  • Secrets or hidden reasoning
  • Exact quotes or required schemas

Precedence: platform policy → system/developer instructions → factual, legal, permission, tool, and schema constraints → user instruction → selected VOICE.md → model defaults.

Progressive adoption

L0 plain to L3 testable.

Teams can begin with Markdown and add structure only when they need deterministic selection, compilation, or validation.

  1. L0

    Plain

    A non-empty Markdown contract. No structured parser required.

  2. L1

    Core

    Valid structured frontmatter plus concrete communication guidance.

  3. L2

    Contextual

    Activation, authority, audience, surface, tone, speech, or hierarchy.

  4. L3

    Testable

    At least one effective deterministic rule or executable inline test.

Deterministic resolution

Discover. Resolve. Select.

The reference algorithm keeps project-wide defaults and local specialization predictable without remote prompt fetching.

01~/.config/voicemd/VOICE.mdoptional global source
02/repo/VOICE.mdproject contract
03/repo/service/VOICE.override.mdnearest source wins
04selected contractprofile + audience + surface + tone

Discovery

Broad to specific

Select at most one candidate per directory. A nearer source has higher precedence.

Inheritance

Local extends

Resolve reviewed local paths first, detect cycles, enforce roots and resource limits.

Merge

Explicit semantics

Scalars replace, objects deep-merge, defined source-level lists append unique, and rules merge by ID.

Activation

Output-aware

Apply to human-facing language; preserve code, raw data, exact quotes, and required schemas.

Reference implementation

From file to checked runtime contract.

The CLI discovers hierarchy, validates conformance, compiles runtime instructions, lints output, runs inline tests, and installs managed adapters.

GitHub README Normative spec PyPI release page

Package publication is a separate release gate from this static site.

quick-start
$ pip install voicemd

$ voicemd init
$ voicemd validate --strict
$ voicemd compile --compact
$ voicemd test

# optional Azure Voice proof lab
$ pip install "voicemd[azure-voice]"
initdiscovervalidatecompilelint testinstalluninstalldoctorserve

Compatibility layer

Use existing extension mechanisms.

VoiceMD does not claim native vendor adoption of the filename. Managed adapters map the contract into official instruction and Agent Skills surfaces.

Coding agents

CodexClaude CodeGemini CLICursorCopilotClineWindsurfOpenCodeAiderAgent Skills

Applications and runtimes

PythonTypeScript.NETHTTP/OpenAPIMCPDockerKubernetesTransformersvLLMOllamallama.cppNemotron VoiceChat

One scenario, three contracts

Observable behavior, not adjectives.

These exact L3 fixtures encode the expected contrast for the same incident facts. They are executable contract examples, not provider output or a model ranking.

Operational

incident_commander

L3 fixture
The service is degraded. No data loss is reported. The ninety-fifth percentile latency is 840 milliseconds. Keep the rollout paused while we verify the cause.

Status → evidence → immediate action

Support

calm_support

L3 fixture
I know this disruption is frustrating. The service is degraded, with 840-millisecond latency, but no data loss is reported. Please keep the rollout paused while the team investigates the unconfirmed cause.

Acknowledge impact → verified state → manageable next step

Executive

executive_brief

L3 fixture
Decision: keep the rollout paused. The service is degraded, with 840-millisecond latency and no reported data loss. The cause is unconfirmed, so resuming now creates avoidable operational risk.

Decision → material evidence → unresolved risk

Recorded implementation evidence

Inspect the bytes behind the Azure example.

Eleven checksum-bound bundles include exact transcripts, playable audio, resolved contracts, event traces, manifests, and a closed SHA-256 inventory.

Open Azure proof
11
verified bundles
9
controlled matrix cells
0
live credentials