ToneProfile Format

Summary

The .toneprofile is a YAML-based portable writing style profile, approximately 150-250 tokens, MIT licensed. It is the primary output of toneforge analyze and the primary input to toneforge inject. The format has three sections: toneforge (metadata: version, timestamp, samples analyzed, word count), style (13 human-readable dimensions), and examples (optional good/bad sample strings for AI calibration).

The 13 style dimensions are: formality, brevity, confidence, warmth, technical_depth, sentences, contractions, hedging, punctuation_habits (array), vocabulary, paragraphs, and passive_voice. No raw embedding or vector is exported — all values are human-readable labels. This keeps the profile editable, diffable, and readable inside any AI context window without specialized tooling.

The format supports 7 injection targets and 5 context mode presets as of 2026-04-11. In v2, the substrate compiler will produce .toneprofile files from a richer evidence base, but the format itself is unchanged — downstream tools consume the same YAML structure regardless of whether it was generated locally (spaCy) or via the v2 substrate pipeline. Format stability is intentional: the moat is adoption, not access control.

Timeline

• 2026-04-11: Context modes design finalized. 5 presets defined (code, pr, report, chat, convo). --contexts flag added to inject and preview. 7 injection targets documented.
• 2026-04-13: v2 research plan established. Substrate compiler will produce .toneprofile from a richer evidence base. Format itself is unchanged; downstream tools unaffected.

Current State

The .toneprofile format is stable at v0.1.0. Seven injection targets are implemented. The --contexts flag on inject skill generates 5 independent context-specific skill files rather than one generic file. The v2 substrate compiler is planned but not yet built — current profiles are generated by the local spaCy analyzer or hosted API. See examples/demo-project/allysoft-pitch.toneprofile for a real-world example.

Key Decisions

• 2026-04-11: YAML over JSON — more compact for prose-friendly key-value data, better token efficiency in context windows.
• 2026-04-11: No raw vector export — human-readable labels only. Keeps profiles editable and auditable without tooling.
• 2026-04-11: 5 context mode presets via --contexts — code and PR contexts need brevity/formality tuned differently than reports or chat. One generic profile injected everywhere is less accurate than 5 targeted ones.
• 2026-04-13: Format frozen as the v2 moat strategy — substrate compiler improves accuracy but emits the same YAML. Adoption of the format is the lock-in mechanism, not the generation pipeline.

Gotchas & Known Issues

• The punctuation_habits dimension is an array (not a scalar), unlike all other style dimensions. Tooling that iterates style dimensions needs to handle the array case.
• examples section is optional. Injection templates must handle its absence gracefully.
• Context mode presets override specific dimensions only — unspecified dimensions inherit the base profile values. This is by design but can surprise users who expect fully independent profiles per context.

Open Questions

• When will the v2 substrate compiler ship? Until then, profile accuracy depends on the spaCy local analyzer, which has known limitations on short samples.
• Should the format version bump to 1.0.0 before the public launch to signal stability?

Sources

• 2026-04-11-context-modes-design.md
• 2026-04-13-v2-research-plan.md