vibevm — boot snippet: project foundation
**Project:** vibevm — a CLI software project manager for spec-driven AI-assisted development.
**Binary:** `vibe`.
**Source of truth:** [`VIBEVM-SPEC.md`](../../VIBEVM-SPEC.md) (project root). This is the entire implementation specification.
Every session starts here. In order:
- Read this file and the rest of `vibevm/vibespecs/boot/` end to end — including the generated `INDEX.md` (the computed boot manifest) and `STATIC.xml` (the priority lane). `vibe` owns the boot order; see `VIBEVM-SPEC.md` §6.
- Read `vibevm/vibespecs/WAL.xml` — current project state (checkpoint, not log).
- Read the relevant PROP/FEAT under `vibevm/vibespecs/common/` and `vibevm/vibespecs/modules/` for the task at hand.
- Only then start work.
If `vibevm/vibespecs/WAL.xml` is older than 24 hours, verify the state with the user before doing destructive work.
See [`CLAUDE.md`](../../CLAUDE.md) (and its identical copies `AGENTS.md` / `GEMINI.md`) for the full text. Authoritative reference: [spec://org.vibevm.core/vibevm/common/PROP-000#commits](../common/PROP-000.xml#commits). Summary only:
- **Attribution — keep this repository human-authored.** Never mark commits, branches, comments, or any artefact as machine-authored. The rule itself (and its copy in PROP-000 §12.1) is the only place in the project where that topic is discussed.
- **Conventional Commits** — short subject, long explanatory body answering *why*.
- **Group commits by meaning** — one logical unit per commit, split mixed working trees.
- **Autonomy on routine changes only** — commit and push routine work without asking; stop and ask for history rewrites, force-push, large blobs, CI/signing changes, and anything whose reversal costs work.
- `refs/book/` — the user's book, read-only reference material.
- A unit whose state is `void` (`@spec/void`, or `state="void"` in a `<status>` element) **asserts nothing** and is not work. It was either split into heirs and left as a pointer to them, or cancelled with no replacement; its text survives only so its name is not reused and inbound links do not break. Do not implement it, do not plan from it, do not count it as outstanding.
- The trap, and the only reason this rule is needed: the prose is unchanged. A tombstone still reads like the requirement it used to be, because it was one. The marker is the only thing saying otherwise, so read it before acting on the paragraph.
- If the unit names successors, they carry the claim and the work is theirs. If it names none, the claim was withdrawn and there is nothing to do.
vibevm's instance of the **two-process-model** flow (`spec://org.vibevm.world/two-process-model/flows/two-process-model/TWO-PROCESS-MODEL#root`) — human and agent as two processes sharing one repository; these are its reading layers, information flowing top-down, the human winning conflicts:
- **Head** (human's memory) — not your concern, but respect that it exists. Human wins conflicts with the spec.
- **WAL** (`vibevm/vibespecs/WAL.xml`) — volatile, rewritten each session, describes *current* state.
- **Spec** (other files under `spec/`) — stable decisions, addressable via `spec://…` URIs.
- **Code** (everything under `crates/`, including each crate's own `tests/`) — artefacts. Losing them is inconvenient; losing the spec is a catastrophe.
Information flows top-down. If code changes first, reconcile up via the **sync-from-code** flow (`spec://org.vibevm.world/sync-from-code/flows/sync-from-code/SYNC-PROTOCOL#root`; also `refs/book/` chapter 3) — propose a spec update, do not rewrite code back.
- **Language:** Rust. See [spec://org.vibevm.core/vibevm/common/PROP-000#language](../common/PROP-000.xml#language).
- **Manifests:** TOML. One `vibe.toml` per node — the role is set by section (`[project]` ⊕ `[package]`, optionally `[workspace]`); lockfile = `vibe.lock`.
- **Terminology:** only eight installable kinds — `flow`, `feat`, `stack`, `tool`, `mcp`, `lang`, `doc`, `app` (the register grows only by owner amendment to `VIBEVM-SPEC.md` §4.1; `app` is anticipated). The owner-approved PROP-054 vocabulary admits `lifecycle` and `phase` as VibeVM terms. `goal` remains prior-art language. `plugin` is permitted only when it precisely means a package-supplied extension/mechanism implementation, compiler plugin or external ecosystem artifact such as Agent Plugin; it is not a stored identity, a synonym for contribution/execution/handler or another installable kind. Machine prose prefers package → extension point/mechanism → contribution → execution → handler/provider. Authoritative amendment: [PROP-054 `##VOCABULARY-ADMITTED`](../common/PROP-054-lifecycle-and-extensions.xml#VOCABULARY-ADMITTED).
- **Repository URLs:** vibevm source = `git@gitverse.ru:vibevm/vibevm.git` / `https://gitverse.ru/vibevm/vibevm`. Package registry = the GitHub organization `https://github.com/vibespecs` (deliberate split-host posture — see `vibevm/vibespecs/boot/90-user.xml` and [PROP-000 §7](../common/PROP-000.xml#registry)). The legacy GitVerse monorepo `git@gitverse.ru:anarchic/vibespecs.git` is read-only transition state.
When the spec is silent on a question:
- Re-read the relevant section of `VIBEVM-SPEC.md`.
- Re-read the relevant chapter in `refs/book/`.
- Look at the closest analog under `refs/src/` (cargo, uv, spec-kit).
- If still unclear: mark the decision with `<!-- REVIEW: … -->`, pick the conservative interpretation, proceed, flag in the end-of-session report. Never silently invent semantic behavior.
- Update `vibevm/vibespecs/WAL.xml` to reflect the *current* state (rewrite, not append — it is a checkpoint).
- Propose a milestone commit if work is a logical unit. For routine work, follow rule 4 above: commit and push using rules 2–3. For non-routine operations, stop and ask the user first.