Skip to content

Vox Golden Example Style Guide

This document defines the coding conventions, frontmatter requirements, and structural rules for all .vox files in the examples/ directory. All contributors and AI agents must follow these rules.


Every .vox file must begin with a structured comment-frontmatter block. This block is parsed by the Vox CI pipeline and the Mens training corpus ingestion pipeline.

// ---
// title: "Descriptive Example Title"
// description: "120-158 character description of what this example demonstrates."
// syntax_version: "0.5.0"
// status: golden | deprecated | archived | experimental
// category: example
// constructs: [actor, workflow, server, table, fn, test]
// last_validated: YYYY-MM-DD
// training_eligible: true | false
// training_weight: 0.0 - 2.0
// difficulty: beginner | intermediate | advanced
// supersedes: ""
// superseded_by: ""
// ---
FieldRequiredDescription
titleYesHuman-readable title with keywords.
descriptionYes120-158 chars describing what is demonstrated.
syntax_versionYesThe Vox version this file targets (e.g., "0.5.0").
statusYesSee lifecycle table below.
categoryYesAlways example for .vox files.
constructsYesVox constructs demonstrated. Used for training and search.
last_validatedYesISO date when vox check last succeeded. Updated by CI.
training_eligibleYestrue for golden only. All others: false.
training_weightYes1.0 default. 1.5-2.0 for exemplary examples. 0.0 for deprecated.
difficultyYesbeginner, intermediate, or advanced.
supersedesNoFilename of the older file this replaces. Empty string if none.
superseded_byNoFilename of the newer file. Set when deprecating.

  • Use snake_case.vox (e.g., crud_api.vox, counter_actor.vox).
  • Names must describe the concept demonstrated, not be generic (never example1.vox).
  • Files in golden/ are the canonical source of truth. archive/ contains deprecated files.

  • Each file should be 20 to 100 lines of Vox code.
  • Demonstrate 1-3 related constructs per file. Do not pack every feature into one example.
  • Files must be self-contained — they must compile and pass vox check <file> independently.

  • Use // line comments to explain non-obvious constructs.
  • Do not over-annotate. Obvious code (variable assignments, simple returns) needs no comment.
  • Every example should include at least one explanatory comment block explaining the core concept.

  • Include at least one @test function that validates the example’s output.
  • Tests make examples runnable in CI and provide a correctness guarantee for Mens training.

When a new Vox syntax version breaks an existing golden example:

  1. Create the new corrected example in golden/ with supersedes: "old_file.vox".
  2. Add superseded_by: "new_file.vox" and status: deprecated to the old file’s header.
  3. Set training_eligible: false and training_weight: 0.0 on the deprecated file.
  4. Move the deprecated file to archive/ directory.
  5. CI will update PARSE_STATUS.md automatically on the next run.

examples/
├── golden/ # Current, validated examples (status: golden)
├── archive/ # Deprecated or superseded examples (status: deprecated|archived)
├── experimental/ # Forward-looking examples for unreleased syntax (status: experimental)
├── STYLE.md # This file
├── PARSE_STATUS.md # CI-generated parse matrix
└── README.md # Overview and lifecycle explanation