VVM Skill

VVM (Vibe Virtual Machine) is a language for writing agentic programs where the LLM acts as the runtime.

---

When to Activate

Activate this skill when:

1. User runs /vvm-boot, /vvm-compile, /vvm-run, /vvm-run-inspect, /vvm-registry-inspect, or /vvm-generate
2. User opens or references a .vvm file
3. User asks about VVM syntax, semantics, or patterns
4. User wants to create an AI-powered workflow

---

Documentation Files

File	Role	When to Read
SKILL.md	Quick reference, triggers	Always first
vvm.md	Execution semantics	When running programs
spec.md	Language specification	For syntax/validation questions
memory-spec.md	Agent memory (portable)	When using persistent agents
patterns.md	Design patterns	When writing programs
antipatterns.md	Anti-patterns	When reviewing programs

---

Quick Reference

Agent Definition

agent researcher(
  model="sonnet",
  prompt="thorough, cite sources",
  skills=["web-search"],
  permissions=perm(network="allow", bash="deny"),
)

Agent Call

result = @researcher `Find papers on {topic}.`(topic)
result = @researcher `Summarize.`(topic, retry=3, timeout="30s")

Agent Memory

agent assistant(model="sonnet", prompt="Helpful.", memory={ scope: "project", key: "user:alice" })
reply = @assistant `Continue.`(request)  # default: memory_mode="continue"
dry = @assistant `Read-only run.`(request, memory_mode="dry_run")
fresh = @assistant `Stateless run.`(request, memory_mode="fresh")

Semantic Predicate

ready = ?`production ready`(code)

if ?`needs more work`(draft):
  draft = @writer `Improve.`(draft)

Pattern Matching

match result:
  case ?`high quality`:
    publish(result)
  case error(kind="timeout"):
    result = @backup `Retry.`(request)
  case error(_):
    log_error(result)
  case _:
    pass

Choice

choose analysis by ?`best approach` as choice:
  option "quick":
    plan = @planner `Minimal plan.`()
  option "thorough":
    plan = @planner `Full plan.`()

Control Flow

# If/elif/else
if condition:
  do_something()
elif other:
  do_other()
else:
  do_default()

# While loop
while not ?`done`(result):
  result = @worker `Improve.`(result)

# For loop
for item in items:
  process(item)

Context Passing

# Implicit input (it)
with input data:
  result = @agent `Process.`()  # uses it == data

# Explicit input
result = @agent `Process.`(data)

Functions

def analyze(topic):
  research = @researcher `Find info on {topic}.`(topic)
  return @analyst `Analyze.`(research)

result = analyze("AI safety")

Error Handling

# Error values (match)
match result:
  case error(_):
    handle_error(result)

# Raised errors (try/except)
try:
  if ?`invalid`(input):
    raise "Invalid input"
except as err:
  log(err)
finally:
  cleanup()

Constraints

draft = @writer `Write report.`(data)

constrain draft(attempts=3):
  require ?`has citations`
  require ?`no hallucinations`

Imports/Exports

# Skill imports
import "web-search" from "github:anthropic/skills"

# Module value imports (agents are local)
from "./lib/research.vvm" import report

# Callable module import
from "./lib/research.vvm" import * as research
result = research(topic="AI", depth="deep")
report = result.report

# Exports (values only)
export result
export summary

Standard Library

# Parallel map
results = pmap(items, process)

# Sequential map/filter/reduce
mapped = map(items, transform)
filtered = filter(items, predicate)
def add(a, b):
  return a + b
total = reduce(items, add, init=0)

# Iterative refinement
final = refine(initial, max=5, done=is_ready, step=improve)

# Named fan-in
ctx = pack(research, analysis, topic=topic)

# Range
for i in range(10):
  process(i)

---

Examples

#	Name	Concepts
01	hello-world	Minimal program
02	simple-agent-call	Agent with input
03	semantic-predicate	? predicates
04	match-statement	Pattern matching
05	if-elif-else	Conditionals
06	while-loop	While loops
07	for-loop	For loops
08	with-input	Context passing
09	agent-options	retry, timeout, backoff
10	code-council	.with() derived agents
11	parallel-pmap	Parallel execution
12	functions	def and return
13	skill-imports	Skill imports
14	module-imports	Module imports
15	error-values	Error value matching
16	try-except-finally	Raised errors
17	choose-statement	AI-selected branching
18	constrain-require	Quality constraints
19	refine-loop	Iterative improvement
20	collection-helpers	map, filter, reduce
21	devils-advocate	Adversarial debate
22	full-research-pipeline	Complex workflow
23	ralph-wiggum-loop	Continuous improvement
24	agent-memory-basic	Memory binding + digest/ledger
25	agent-memory-modes	memory_mode: continue/dry_run/fresh
26	agent-memory-multi-tenant	Per-key isolation
27	agent-memory-parallel-safe	pmap-safe persistence
28	ref-composition	Ref composition patterns
29	ref-loop-accumulation	Accumulating refs in loops
30	materializer-pattern	Materializing refs
31	run-inspector	Inspecting run state
32	ouroboros	Self-modifying workflow
33	wisdom-of-crowds	Ensemble voting
34	hydra	Multi-headed agents
35	forge	Agent factory
36	inputs	Input declarations
37	debate	Module composition

---

Commands

/vvm-boot

Initialize VVM for new or returning users. Detects existing files and provides onboarding.

/vvm-compile <file.vvm>

Validate a VVM program without executing. Reports errors and warnings with line numbers.

/vvm-run <file.vvm>

Execute a VVM program. You become the VVM runtime and execute statements sequentially, spawning subagents for agent calls.

/vvm-run-inspect

Inspect run state from filesystem, SQLite, or Postgres backends without re-running the workflow.

/vvm-registry-inspect <@handle/slug|https://...>

Inspect a remote module contract and cache metadata without executing the workflow.

/vvm-generate

Generate a VVM program from a natural language description. Analyzes intent, maps to VVM constructs, applies best practices, and produces well-structured code. Asks clarifying questions if the request is ambiguous.

---

Key Principles

1. Minimal syntax - Familiar indentation-based blocks
2. Explicit AI boundary - Agent calls are syntactically distinct (@agent)
3. Eager execution - No lazy evaluation, sequential by default
4. Semantic control flow - Branch on meaning, not just booleans
5. Two error channels - Values (match) vs raised (try/except)
6. Explicit parallelism - Only pmap runs concurrently