Voice Framework Overview

Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.

Natural voice evidence contract

The evidence and ownership ADR and versioned evidence ledger pin the eight inducted sources and distinguish research findings from editorial policy and product qualification. Additional evaluation and retrieval papers remain deferred pending full-method assessment. This evidence contract does not claim that author profiles, revisions or human quality qualification have shipped. Existing output-mode resolution and the default unaltered behavior remain the integration contract.

For implemented editorial review APIs, see contextual diagnostics and the labeled fixture report. These return located, reviewable findings and explicit exceptions without an authorship score or a publication gate. Legacy validator scores remain deprecated adapters.

The voice framework addon helps teams define and reuse a consistent writing voice. Use it when documentation, release notes, marketing copy, or internal reports need a named style that can be applied, analyzed, adjusted, and shared across sessions.

Common Use Cases

• Rewrite a draft in a technical, executive, friendly, or conversational register.
• Create a project voice profile from a description or sample text.
• Blend two profiles when content needs both precision and approachability.
• Analyze whether a document matches the intended house style before publication.

Why Voice Profiles

Pattern checks are useful for catching obvious problems, but they do not define what good writing should sound like. Voice profiles specify tone dimensions, vocabulary preferences, structural patterns, and authenticity markers so the assistant has a positive target to match.

This addon replaces the earlier `banned-patterns.md` and `ai-pattern-detection` skill, which are now deprecated.

Built-in Profiles

Located in `@$AIWG_ROOT/agentic/code/addons/voice-framework/voices/templates/`.

technical-authority

Direct, precise, confident. Appropriate for API documentation, architecture decision records, engineering specifications, and any content where the audience expects expertise and precision.

Characteristics: high confidence (0.9), moderate formality (0.7), low warmth (0.3). Favors specific examples, acknowledges tradeoffs, uses "specifically," "in practice," "the key constraint here is."

friendly-explainer

Approachable, encouraging, patient. Appropriate for tutorials, onboarding guides, educational content, and situations where reducing friction matters more than demonstrating expertise.

Characteristics: high warmth, lower confidence (to invite engagement rather than declare authority), favors conversational sentence structure and progressive disclosure.

executive-brief

Concise, outcome-focused. Appropriate for business cases, stakeholder communications, executive summaries, and any content where time-to-decision is the primary concern.

Characteristics: minimal hedging, leads with conclusions, uses specific metrics, avoids technical detail unless directly relevant to decisions.

casual-conversational

Relaxed, personal, opinion-forward. Appropriate for blog posts, social media, newsletters, and community content where authenticity matters more than formality.

Characteristics: first-person perspective, opinions stated directly (not hedged), shorter paragraphs, conversational connectives.

Core Skills

voice-apply

Transform existing content or generate new content in a specified voice.

Natural language triggers: "Write this in technical voice," "Make it more casual," "Use the executive-brief voice," "Transform this to match [example text]."

voice-create

Generate new voice profiles from descriptions or example text.

Natural language triggers: "Create a voice for API documentation," "Make a voice profile from this sample," "Define a new voice that's precise but friendly."

New profiles are saved to `.aiwg/voices/` (project-scoped) or `~/.config/aiwg/voices/` (user-scoped).

voice-blend

Combine multiple profiles with weighted ratios.

Natural language triggers: "Blend 70% technical with 30% friendly," "Mix executive and casual voices," "Combine these two profiles."

voice-analyze

Analyze the current voice characteristics of existing content.

Natural language triggers: "What voice is this written in?," "Analyze the tone of this document," "How formal is this content?"

Output is a structured analysis mapping the content against the profile schema dimensions (formality, confidence, warmth, energy, vocabulary patterns, structural patterns).

output-mode-guide

Configure, apply, troubleshoot, or extend composable output modes. Natural language triggers include “use an output mask,” “use Wittgenstein-inspired style,” “apply engineering standards language,” and “create my preferred syntax style.”

Profile Resolution Order

For runtime-selectable cross-kind composition, see `@$AIWG_ROOT/agentic/code/addons/voice-framework/docs/output-modes.md`.

When a skill looks for a voice profile by name, it checks:

1. `.aiwg/voices/` — Project-specific profiles 2. `~/.config/aiwg/voices/` — User-wide profiles 3. `@$AIWG_ROOT/agentic/code/addons/voice-framework/voices/templates/` — Built-in profiles

Project profiles override user profiles, which override built-ins. This means you can create a project-local `technical-authority.yaml` that overrides the built-in with project-specific vocabulary preferences.

Voice Profile Schema

Profiles are YAML files defining tone dimensions, vocabulary preferences, structural patterns, and perspective settings. The schema is validated by `@$AIWG_ROOT/agentic/code/addons/voice-framework/schemas/voice-profile.schema.json`.

Key fields:

• `tone.formality` (0–1): 0 = casual, 1 = formal
• `tone.confidence` (0–1): 0 = tentative, 1 = assertive
• `tone.warmth` (0–1): 0 = clinical, 1 = personable
• `vocabulary.prefer` / `vocabulary.avoid` / `vocabulary.signature_phrases`
• `structure.sentence_length`, `structure.use_lists`, `structure.include_examples`
• `perspective.person` (first/second/third), `perspective.opinion_level`
• `authenticity.acknowledge_tradeoffs`, `authenticity.use_specific_numbers`

Installation

Use AIWG to complete this documented outcome: Installation
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.

References

• Quickstart — Apply your first voice profile
• `@$AIWG_ROOT/agentic/code/addons/voice-framework/docs/output-modes.md` — Select and compose runtime output modes
• `@$AIWG_ROOT/agentic/code/addons/voice-framework/docs/custom-output-modes.md` — Author a personal syntax or project house style
• `@$AIWG_ROOT/agentic/code/addons/voice-framework/docs/output-mode-integration.md` — Integrate a transformer or validator
• `@$AIWG_ROOT/agentic/code/addons/voice-framework/docs/output-mode-troubleshooting.md` — Diagnose selection and runtime problems
• `@$AIWG_ROOT/agentic/code/addons/voice-framework/voices/templates/` — Built-in profile files
• `@$AIWG_ROOT/agentic/code/addons/voice-framework/schemas/voice-profile.schema.json` — Profile schema
• `@$AIWG_ROOT/agentic/code/addons/voice-framework/schemas/output-mode-profile.schema.json` — Output-mode profile schema