VoiceMD

A version-controlled communication contract for AI agents.

VOICE.md defines how an agent communicates: how it explains uncertainty, disagrees, adapts to an audience, structures an answer, and speaks through a voice interface. It does not grant capabilities or override facts, safety, permissions, tools, exact quotations, or required schemas.

Website · Specification · JSON Schema · Azure proof · Azure Voice Lab · Security model

Status: independent draft 0.1.0-draft.2, dated 2026-08-24, with Python reference implementation 0.1.0a3. Usable and testable; not a vendor-adopted or standards-body-approved format.

AGENTS.md      what the agent does and how it works
DESIGN.md      how the product looks and behaves visually
STORYLINE.md   how the experience unfolds
VOICE.md       how the agent communicates and interacts

See the difference

The three contract-compliant reference outputs below use the same synthetic incident facts. They are deterministic examples derived from the bundled L3 contract cases; only the selected VOICE.md changes.

Known facts: service degraded; p95 latency 840 ms; no data loss reported; cause not confirmed; rollout paused.

Listen to the recorded Azure samples and inspect their exact transcripts.

Recorded Azure proof snapshot

One local proof run on 2026-08-24 produced 11 manifests that passed the evidence schema at capture time and are hash-bound in the public snapshot. The synthetic 3×3 matrix completed all nine provider calls and retained every exact output together with its deterministic contract-check record.

The proof page includes playable samples, exact transcripts, deterministic contract-check records, and the authority-boundary showcase. These observations are not a benchmark, SLA, quality score, fixed model-identity claim, or production readiness certification. Microsoft currently documents GPT Realtime 2.x as preview; recheck availability and lifecycle before production use.

Install and run

Python package

python -m pip install voicemd

voicemd init --mode full
voicemd validate --strict
voicemd compile --profile executive_brief
voicemd test

For Azure audio, Realtime, and transcription demos:

python -m pip install 'voicemd[azure-voice]'
voicemd-azure doctor

Python 3.10–3.14 is supported.

Zero-install Markdown

Copy the simple template and include it only when generating human-facing language:

cp templates/simple/VOICE.md ./VOICE.md

from pathlib import Path

voice = Path("VOICE.md").read_text(encoding="utf-8")
system_prompt = BASE_SYSTEM_PROMPT + "\n\n" + voice

This is conformance level L0 Plain and needs no package or parser. Minimal loaders are also available in Python, Node.js, and shell:

python lite/voice_loader.py
node lite/load-voice.mjs
bash lite/load-voice.sh

Write a contract

A VOICE.md can be plain Markdown or structured YAML frontmatter plus Markdown. The structured form can be selected, compiled, linted, and tested.

---
voice_spec: "0.1"
kind: VoiceContract
name: "Direct technical advisor"
version: "1.0.0"
activation:
  mode: contextual
  include: [chat, explanation, document, spoken]
  exclude: [code, structured_data, tool_call, exact_quote]
authority:
  may_control: [tone, vocabulary, structure, verbosity]
  must_not_control: [facts, safety, permissions, tools, schemas]
identity:
  sounds_like:
    - A practitioner who has done the work
  not_like:
    - A marketing copywriter
epistemics:
  uncertainty: State the missing variable and why it matters.
interaction:
  disagreement: Correct false premises directly and provide the better model.
lexicon:
  forbidden: ["Great question", "Absolutely!"]
profiles:
  spoken:
    surface: spoken
    overrides:
      response:
        max_words: 80
---

# Core behavior

Lead with the conclusion. Prefer concrete examples and failure modes over
abstract claims.

Start from the smallest suitable template:

Coding-agent adapters

voicemd install --target all --mode auto
voicemd doctor

auto installs a small managed bootstrap and a voice-contract Agent Skill. The harness loads the full contract for human-facing output, not for code patches, tool calls, raw data, or mandatory JSON.

explicit requires native invocation where supported:

voicemd install --target all --mode explicit

• Codex: $voice-contract
• Claude Code, GitHub Copilot CLI, Cursor: /voice-contract
• portable marker after a contract is already available: @voice or voice:on
• Aider: start the opted-in session with aider --config .aider.voice.yml

Included compatibility adapters cover Codex, Claude Code, Gemini CLI, Cursor, GitHub Copilot, Cline, Windsurf, OpenCode, Aider, and generic Agent Skills-compatible harnesses. Compatibility does not imply vendor endorsement or native recognition of the VOICE.md filename. See docs/HARNESS_COMPATIBILITY.md.

Applications and sidecar

Compile a selected contract directly:

voicemd compile --profile executive_brief
voicemd compile --profile voicechat --compact --max-chars 5000
voicemd compile --profile nemotron_voicechat --format nemotron-ascii
voicemd compile --profile executive_brief --format sha256

Or use the provider-neutral HTTP sidecar:

voicemd serve --host 127.0.0.1 --port 8765
curl 'http://127.0.0.1:8765/v1/voice/prompt?surface=chat&audience=engineer'

Endpoints:

• GET /health
• GET /v1/voice/contract
• GET /v1/voice/prompt
• POST /v1/voice/lint

The repository includes a Python API/middleware, TypeScript and .NET clients, OpenAPI, optional MCP server, Docker Compose, Kubernetes sidecar, and examples for OpenAI-compatible servers, Transformers, vLLM, Ollama, and llama.cpp.

Azure Voice Proof Lab

The optional proof harness compares three generation deployments against three contrasting L3 spoken contracts. Separate commands exercise gpt-live-transcribe and the transcription-to-Realtime authority boundary.

Create an ignored .env file with mode 0600; the CLI loads it by default:

AZURE_OPENAI_ENDPOINT=https://YOUR-RESOURCE.openai.azure.com
AZURE_OPENAI_API_KEY=YOUR-KEY

chmod 600 .env

voicemd-azure doctor
voicemd-azure matrix --scenario degraded-service-en
voicemd-azure gallery

matrix performs nine billable calls by default. Restrict it while developing:

voicemd-azure matrix \
  --scenario degraded-service-en \
  --lanes realtime-mini

Raw live transcription deliberately runs with VoiceMD activation disabled:

voicemd-azure transcribe \
  --input-audio input-24k-mono.wav \
  --language en \
  --delay medium

The end-to-end authority demo first stores raw ASR, then sends it as untrusted user speech to a fresh VoiceMD-governed Realtime response:

voicemd-azure showcase \
  --input-audio input-24k-mono.wav \
  --voice examples/azure-voice/contracts/executive_brief/VOICE.md

Each run writes a schema-validated manifest, SHA-256 inventory, exact context snapshots, sanitized event timing, transcript, and playable WAV where applicable. Credentials stay in environment state or an ignored environment file. Manifests store only endpoint fingerprints; WebSocket and REST redirects are rejected. Read the paid-call warning, PCM input requirements, complete commands, and proof boundaries in examples/azure-voice/README.md.

Discovery, hierarchy, and precedence

The reference implementation resolves sources broad-to-specific:

1. Explicit --path values, or VOICE_MD, replace automatic discovery.
2. An optional global contract is read from ${VOICE_MD_HOME:-~/.config/voicemd}.
3. From project root to the current directory, at most one file wins per level: VOICE.override.md, VOICE.md, .voice/VOICE.override.md, then .voice/VOICE.md.
4. Local extends files load before the file that extends them.
5. More specific values win; rules and tests merge deterministically by ID.

repo/VOICE.md                         organization defaults
repo/apps/VOICE.md                    product behavior
repo/apps/support/VOICE.override.md   support-agent override

Remote extends are rejected. Explicit, discovered, and inherited sources must remain inside an approved canonical root; symlinks and .env files cannot widen that boundary. File, aggregate, source-count, YAML-node, alias, and inheritance-depth limits are enforced.

Activation and authority

Apply VoiceMD to:

• chat, explanations, messages, reports, summaries, and UI copy;
• audience-specific or tone-specific human communication;
• spoken dialogue and TTS-friendly rendering.

Do not transform:

• code, patches, SQL, or configuration syntax;
• tool calls or tool results;
• required JSON/XML/YAML or another exact schema;
• exact quotations, raw data, or raw transcripts;
• faithful translation unless adaptation is explicitly required.

Higher-priority safety, facts, permissions, tools, legal requirements, and application instructions always win. VOICE.md is communication policy, not an authorization system or prompt-injection security boundary.

Conformance and portability

An invalid or empty contract is nonconforming. The exact selected profile/audience/surface/tone result is validated again before compilation, linting, sidecar output, or provider submission.

Structured frontmatter uses the YAML 1.2 JSON schema subset. Canonical JSON and SHA-256 use RFC 8785 JCS after VoiceMD's stricter portable safe-integer checks and exclude host filesystem paths.

Run the language-neutral core suite with the independent TypeScript verifier:

node integrations/typescript/generated/conformance-verifier.js \
  conformance/vectors.json

The 57 vectors cover merge, selection, compact rendering, JCS, and hashing. This bundled Python-independent verifier is not a complete second implementation of YAML parsing, filesystem discovery, or runtime adapters.

CLI reference

Use voicemd <command> --help or voicemd-azure --help for full options.

Repository map

Governance is explicit: GOVERNANCE.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, ROADMAP.md, and CHANGELOG.md.

Security and release integrity

• Sources are root-contained; remote extends, symlink escapes, .env paths, unbounded YAML expansion, and invalid selected contracts fail closed.
• Harness installation is atomic, ownership-tracked, and non-destructive to modified or unowned content.
• The HTTP sidecar binds to 127.0.0.1 by default and is not an authenticated public gateway.
• Azure credentials never belong in CLI arguments, captured output, manifests, transcripts, or Git.
• Release artifacts are built twice with a pinned toolchain and compared byte-for-byte.
• BUILD_INFO.json, SHA-256 checksums, SPDX SBOM, and unsigned in-toto/SLSA provenance bind artifacts to a source snapshot.
• GitHub publication adds hosted CI and signed attestations; local unsigned provenance proves consistency, not publisher identity.

Verify a checked-out release without executing artifact code:

python scripts/verify_release.py \
  --distributions release \
  --metadata release \
  --source-root . \
  --source-revision "$(jq -r .source_revision release/BUILD_INFO.json)" \
  --release-revision "$(jq -r .release_revision release/BUILD_INFO.json)"

See docs/SECURITY_MODEL.md and docs/RELEASE_CHECKLIST.md.

cp templates/simple/VOICE.md ./VOICE.md

python -m pip install voicemd
voicemd init --mode full
voicemd validate --strict
voicemd install --target all --mode auto
voicemd doctor

python -m pip install 'voicemd[azure-voice]'

AZURE_OPENAI_ENDPOINT=https://YOUR-RESOURCE.openai.azure.com
AZURE_OPENAI_API_KEY=YOUR-KEY

chmod 600 .env

voicemd-azure doctor
voicemd-azure matrix --scenario degraded-service-en --lanes realtime-mini
voicemd-azure gallery

Boundaries and prior art

VoiceMD does not claim deterministic model behavior, voice cloning, acoustic identity, vendor adoption, independent security certification, or standards body approval. The filename and brand-voice concept have prior art, including the independent Efeonce voice.md project; VoiceMD does not claim invention of the filename or affiliation with that project. See docs/BRAND_COMPATIBILITY.md.

License

Apache License 2.0. See LICENSE and NOTICE.