verona-conventions
Skill3.7k starsChanged 3 months agoMITView on GitHub
Verona compiler coding conventions, C++ style, trieste patterns, and project structure. Applies when writing or reviewing Verona compiler code.
Trending
Quiet this year.about the whole repository
Who's talking about microsoft/verona
- A Hacker News story“Microsoft Project Verona: Research programming language for concurrent ownership”Hacker News · Jan 17, 2020 · 142 points
- A Hacker News story“Project Verona FAQ”Hacker News · Feb 10, 2020 · 29 points
- A Hacker News story“Project Verona: Research programming language for concurrent ownership”Hacker News · Jan 16, 2020 · 7 points
- A Hacker News story“Microsoft/Verona”Hacker News · Jan 18, 2020 · 3 points
- A Hacker News story“Concurrent Ownership in Verona”Hacker News · Dec 14, 2022 · 2 points
The biggest 5 of 18 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 18
Talked about on GitHub and Hacker News (18 times).
On GitHub · 12
- Dec 31, 2023Check ideas from Verona language for concurrency — lambdaclass/concrete0 reactions
- Jul 21, 2023Add Verona — ChessMax/awesome-programming-languages0 reactions
- Jul 13, 2023Move the Verona compiler to microsoft/verona — microsoft/Trieste0 reactions
- Oct 24, 2022Optimise for waking an empty queue — microsoft/verona-rt0 reactions
- Oct 24, 2022Token source — microsoft/verona-rt0 reactions
7 more on GitHub
- Oct 20, 2022Small optimisations and refactors around message send and receive — microsoft/verona-rt0 reactions
- Jul 29, 2022Don't run CI on doc-only changes — microsoft/CCF0 reactions · 4 comments
- Aug 26, 2021Enable passthrough to an underlying allocator — microsoft/snmalloc0 reactions · 1 comment
- Jan 25, 2021Meta: Some interesting pointers to borrow ideas — flix/flix0 reactions · 1 comment
- Jan 4, 2021Meta: Some interesting pointers to borrow ideas — HigherOrderCO/Kind0 reactions
- Jun 18, 2020Refactor Pal and LargeAlloc interaction. — microsoft/snmalloc0 reactions
- Jan 27, 2020Automating keeping snmalloc up to date. — SchrodingerZhu/snmalloc-rs0 reactions · 2 comments
On Hacker News · 6
- Jan 17, 2020Microsoft Project Verona: Research programming language for concurrent ownership142 points · 16 comments
- Feb 10, 2020Project Verona FAQ29 points · 8 comments
- Jan 16, 2020Project Verona: Research programming language for concurrent ownership7 points
- Jan 18, 2020Microsoft/Verona3 points
- Dec 14, 2022Concurrent Ownership in Verona2 points
1 more on Hacker News
- Sep 17, 2023Microsoft Project Verona, a research programming language1 point
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- add-testSkill
- debugSkill
- docs-updateSkill
- reviewSkill
- testsuiteSkill
- vbci-memorySkill
- verona-codingSkill
- verona-type-inferenceSkill
- add-testSkill
- docs-updateSkill
- reviewSkill
- testsuiteSkill
- vbci-memorySkill
- verona-codingSkill
- verona-conventionsSkill
- verona-type-inferenceSkill
The file
We split this skill into the rules it gives an agent
11 rules. About 0 are common, 4 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 17
Use constexpr/consteval, structured bindings, if constexpr, std::span, [[nodiscard]].
- Very specific: line 18
Prefer static constexpr over #define for constants.
- Very specific: line 25
Clone shared nodes: Always clone() nodes inserted into multiple AST locations.
- Very specific: line 29
WF declarations: Every pass declares output shape.
- Very specific: line 37
Run vc from build/: dist/vc/vc build ../testsuite/v/hello.
- Distinctive: line 43
Treat compile-time and runtime test failures as real regressions until they are investigated on the current baseline.
- Very specific: line 48
Do NOT write use "_builtin" — it is always implicitly available.
- Very specific: line 58
No semicolons after closing braces of for, if, while.
- Distinctive: line 100
Before speculative interpreter/runtime changes, explain the evidence and proposed fix and get feedback.
- Distinctive: line 103
Write targeted tests that expose the bug before fixing.
- Distinctive: line 105
Do not describe runtime behavior as flaky or dismiss it as harness noise without first reproducing and tracing it to a concrete cause.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Verona Compiler Conventions
C++ Style (C++20)
snake_casefor functions, variables, namespaces.PascalCasefor types/classes.- Token definitions use
PascalCase:inline const auto TypeName = TokenDef(...). - Allman braces (opening brace on own line). Exception: single-line lambdas.
- No
goto. Use flags, early returns, or helper functions. #pragma once, not include guards.- Project headers first, then system/library headers separated by a blank line.
- Use
constexpr/consteval, structured bindings,if constexpr,std::span,[[nodiscard]]. - Prefer
static constexprover#definefor constants.
Trieste Patterns
- Node construction:
Node n = SomeTokencreates a node. NOTauto n = SomeToken(copies TokenDef). - Child access:
n / ChildToken(named WF accessor), notn->at(i)(positional). - Append children:
node << child. Set value:node ^ value. Duplicate:clone(). - Clone shared nodes: Always
clone()nodes inserted into multiple AST locations. - Token comparison:
node->type() == OtherToken, NOTnode == other_node(compares pointers). - Error handling:
err(node, "message")wraps inError << ErrorMsg << ErrorAst. - Tree mutation:
traverse()iterators are invalidated byreplace()/erase(). Collect first, mutate after. - WF declarations: Every pass declares output shape.
<<=for children,++for zero-or-more,|for choices. - Symbol table:
lookup()walks up + follows includes.lookdown()searches own symtab only, no includes.look()is immediate, no flags. - Pass structure:
PassDefwith name, WF, direction (dir::topdown/dir::bottomup/dir::once), rewrite rules.pre()/post()hooks.
Build & Test
- Build in
build/directory.ninja installto build. Usedist/vc/vcanddist/vbci/vbci(installed binaries have_builtin). - Rebuild with
ninja installbefore debugging or validating compiler/runtime behavior on the current branch. - Run
vcfrombuild/:dist/vc/vc build ../testsuite/v/hello. Do NOT cd into source dir. - Debug with the binaries under the active build directory's
dist/tree. Do not use non-installed build outputs when validating behavior. ctest --output-on-failure -j$(nproc)for full test suite.-p <passname>stops after a pass.--dump_passes=<dir>dumps intermediate ASTs.- Golden files:
ninja update-dump exit_code.txthas NO trailing newline (printf '0', notecho).- Treat compile-time and runtime test failures as real regressions until they are investigated on the current baseline. Do not assume a failure predates your change without verification.
Test Conventions
- Tests in
testsuite/v/must be self-contained. No external deps, nouse "https://...". - Do NOT write
use "_builtin"— it is always implicitly available. - Bitmask exit code pattern:
var result = 0;thenif cond { result = result + N; }with powers of 2. Exit 0 = all passed. - Compile-error tests:
exit_code.txt: 1incompile/, norun/directory. - Structure:
testsuite/v/<name>/<name>.vwith golden dirs<name>/<name>/compile/and<name>/<name>/run/. - FFI tests must include at least one reachable FFI call from their lib to trigger init function reification.
Verona Source Syntax
- Class definitions:
myclass[T] { ... }(noclasskeyword). - Fields need semicolons:
val: T;. Nolet/varon class fields. - No semicolons after closing braces of
for,if,while. new { field = val }— no class name afternew.use Ximports for unqualified lookup.use "url"for packages._builtinis always implicit.(obj.field)(args)to callapplyon field access result.Type(args)constructor sugar callscreatemethod (e.g.,callback(f)→callback::create(f)).x.methodfor zero-arg methods (no parens).!exprfor boolean negation.- Array literals:
::(expr, ...). - Match:
(match expr { (pattern) -> body; ... }) else (default). - FFI calls:
:::name(args)for direct FFI,ffi::func(args)for_builtin/ffi/wrappers. - FFI data passing: arrays pass as pointers to their data (e.g.,
array[u8]→uint8_t*), objects pass as pointers to their fields (like a C struct). No wrapper types cross the FFI boundary. - Packages:
use "url" "tag"imports from a git repo.use "~/dev/pkg" "main"works for local repos.
Architecture
- Small, composable passes. Many small passes > few large ones.
- Layered dependencies — lower layers never depend on higher ones.
- Frontend (vc, passes 0–9): parse → structure → ident → sugar → functype → dot → application → anf → infer → reify.
- Backend (vbcc library, passes 10–13): assignids → validids → liveness → typecheck.
assert()liberally for invariants.- Errors are AST nodes, not exceptions.
Adding New Ops/Builtins
Adding a new bytecode op requires updates in ~15 places across the codebase. Use this checklist:
- Token def:
include/vbcc.h(token),include/vbci.h(Op enum) - Frontend WFs in
vc/lang.h:wfExprDot,wfPassDot(with<<= Args),wfBodyANF,wfPassANF(with<<= wfDst * wfSrc) - Frontend passes:
dot.cc(builtin reg),anf.cc(lowering),infer.cc(type tracking),reify.cc(IR transform) - Backend WFs in
include/vbcc.h:wfStatement,wfIR Defpattern invbcc/lang.h: manually maintained list — MUST include if op has a dstLocalId- Liveness in
vbcc/passes/liveness.cc: manually categorized ops — add to correct use/def category - Bytecode in
vbcc/bytecode.cc: encoding handler - Type check in
vbcc/passes/typecheck.cc: if needed - Interpreter in
vbci/thread.cc: op handler + op name in name array
Missing items 5 or 6 causes "undefined register" errors in later passes, not at the registration site.
Debugging
- Trace data flow, not just error sites. Root cause is often upstream.
- For tricky compiler/runtime/FFI bugs, do principled analysis first: reproduce, trace, inspect dumps, and localize the fault before changing semantics.
- Before speculative interpreter/runtime changes, explain the evidence and proposed fix and get feedback.
- "Bad type" runtime errors usually mean unrefined default literals in compiler output. Check infer pass dump.
node->type() == other->type()for token comparison, NOTnode == other_node.- Write targeted tests that expose the bug before fixing.
- Runtime failures matter as much as compile-time failures. Investigate both with the current branch's
dist/binaries. - Do not describe runtime behavior as flaky or dismiss it as harness noise without first reproducing and tracing it to a concrete cause.
- Durable Verona-specific workflow rules belong in this skill or the repo
AGENTS.md, not in agent-specific memory stores.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

