# Write a lang package {#root} @status:doc/work @audience:author [p01] A lang package teaches an agent how to write in a language or a notation: the idioms, the constraints, the shape of a good file. This page writes one and explains how vibe recognises it as a language discipline. [p02] ```prompt Create a lang package org.acme/sql-style in the current VibeVM project, as an in-tree package under vibevm/vibepacks/: a guide on how our team writes SQL. Give it a boot snippet that names the three rules an agent must always follow, and a guide document with the full idioms, examples and the reasons behind them. Run vibe check on it. ``` - needs: the vibevm skill installed for your agent; a project with `vibe.toml` at the root outcome: `vibevm/vibepacks/org.acme/sql-style/v0.1.0/vibe.toml` declares `kind = "lang"` with a boot snippet; the guide under `vibevm/vibespecs/` has anchored sections the snippet cites; `vibe check` reports no errors - assert: `vibe check --path vibevm/vibepacks/org.acme/sql-style/v0.1.0 --quiet` - assert: `grep -q "kind = \"lang\"" vibevm/vibepacks/org.acme/sql-style/v0.1.0/vibe.toml` ## What happens {#what-happens} [p03] The agent creates the package skeleton, writes the guide and its snippet the way a flow's are written, and sets the kind to `lang`. The difference from a flow is the genre, not the mechanics. A flow says how the team works; a lang package says how to write in something. The kind tells an agent, a [registry](../glossary/index.xml#registry) and the site which is which before the file is opened. > [p04] `kind ∈ {flow, feat, stack, tool, mcp, lang, doc, app}` — eight kinds; `mcp` shipped with [PROP-027](../modules/vibe-mcp/PROP-027-mcp-packages.xml); `doc` and `app` admitted by [PROP-057](PROP-057-documentation-packages-and-site.xml) through the `VIBEVM-SPEC.md` §4.1 amendment of 2026-09-12 (pending the owner's ratification at the merge of the docs-2026-09 branch; the code learns the two kinds in that campaign's phase 2). (§Invariants `INV-VOCABULARY` in this file carries the same list.) > > ## What a lang package is, and is not {#what-a-lang-is} [p05] The genre is wider than programming languages: a guide to a query language, a configuration notation, a documentation dialect or a house style of a language all fit. What does not fit is a bundle of tools; that is a stack. The examples in the public registry are the AI-Native language guides for Rust, TypeScript and Go, each shipping a guide, a set of cards and a runnable toolchain. [p06] An AI-Native language is recognised by one thing only: its dependency on the shared discipline core, `org.vibevm.ai-native/core-ai-native`. Not by its group, not by its name. A third party may publish its own language discipline in its own group and be recognised the same way, so the discipline is not a closed club. > [p07] **`core-ai-native`** (flow) — the language-neutral discipline core. It stands > ALONE: it is the shared foundation every language family requires, not itself > an aggregator (there is nothing to aggregate beneath a foundation), so no > `core-ai-native-lang` / `-mcp` exist. Each `-lang` requires it. > > ## When a language brings tools {#families} [p08] A language guide that also ships tools, a checker, a formatter, a type oracle, becomes a [family](../glossary/index.xml#family). The guide package is `-lang`; a server package `-mcp` serves the same tools to agents; a bundle `` pins both at one version. The members move in unison; a consumer requires the bundle and gets a tested set. > [p09] A **package family** is a set of packages sharing a `` stem and > delivering one coherent capability across three roles: > > > [p10] Within a family the members move in **unison**: a content change to any member > bumps EVERY member of that family to one shared version, and the aggregator's > version IS that family version. > > [p11] The family stem leads every named surface: crates, binaries, [skills](../glossary/index.xml#skill) and the server all carry the `` prefix, so everything of one language sorts and reads together. > [p12] The family stem is language-FIRST and reaches every named surface a family > ships, not only the package identities. Each crate, binary, agent skill, and > MCP server carries the `` prefix: > > ## By hand {#by-hand} [p13] 1. Create the package slot, then set `kind = "lang"` in its [manifest](../glossary/index.xml#manifest): [p14] ```sh vibe init package org.acme/sql-style ``` ```output Creating package `org.acme/sql-style` in `/work` ✓ created vibevm/vibepacks/org.acme/sql-style/v0.1.0/vibe.toml ✓ created vibevm/vibepacks/org.acme/sql-style/v0.1.0/vibevm/vibespecs/boot/10-tool-sql-style.md ✓ created vibevm/vibepacks/org.acme/sql-style/v0.1.0/README.md • kept vibevm/vibespecs/boot/INDEX.md (regenerated) • kept CLAUDE.md (regenerated) • kept AGENTS.md (regenerated) • kept GEMINI.md (regenerated) Done. Project `org.acme/sql-style`: 3 files created, 4 kept. Next: • edit vibevm/vibespecs/boot/00-core.md and vibevm/vibespecs/common as your project takes shape • install packages with `vibe install :` (e.g. flow:wal) ``` [p15] 2. Inside the slot, write `vibevm/vibespecs/boot/sql-style.xml` with the rules an agent must follow every time. Put the guide under `vibevm/vibespecs/lang/sql-style/`, with the reasons, the idioms and the examples. [p16] 3. Declare `[boot_snippet] source = "vibevm/vibespecs/boot/sql-style.xml"`, `category = "stack"`, so that the language rules come after the team's flows in a consumer's reading list. [p17] 4. Check: `vibe check --path vibevm/vibepacks/org.acme/sql-style/v0.1.0`. ## Edge cases and rules {#edge-cases} [p18] What a language brought that can be run is answered by `vibe tools`, not by the kind: the [boot lane](../glossary/index.xml#boot-lane) says which disciplines are installed, the tools registry says what they brought. [p19] Before the `lang` kind existed, language guides were stacks; a `stack` package that is really a guide should move to `lang` at its next version, so that the word means one thing.