Стартовая полоса: как агент читает проект

Порядок чтения

03Сессия агента начинается с файла инструкций, который читает его производитель: CLAUDE.md, AGENTS.md или GEMINI.md. В конце этого файла стоит короткий блок, который поддерживает vibe, и блок говорит: сначала прочитай vibevm/vibespecs/boot/STATIC.md целиком, потом открой vibevm/vibespecs/boot/INDEX.md и прочитай каждый файл, который он называет, по порядку. Вот и весь старт: три шага, и все — чтение.

04 Session-start order: the CLAUDE.md / AGENTS.md / GEMINI.md redirect → vibevm/vibespecs/boot/STATIC.xml (if present) → vibevm/vibespecs/boot/INDEX.md and the entries it names, in order.

05STATIC.md — приоритетная полоса. В ней текст, который должен оказаться перед агентом раньше всего остального; он собран из пакетов, попросивших читать себя именно так, текст каждого пакета ровно один раз. Файл существует, только когда какой-то пакет об этом попросил; у проекта, все пакеты которого читаются по требованию, приоритетной полосы нет, и vibe tree печатает STATIC.md: (none), как выше. Проект, который держит свои стартовые файлы в XML-диалекте, получает вместо него STATIC.xml с тем же содержимым. Он меняется, только когда меняется набор пакетов или их версии, и этим дёшев: хост агента может держать его в кэше между сессиями.

06 What STATIC is (the owner's definition, refined): the generated static boot lane is a CACHE-STABLE PREFIX in LLM-economy terms. It is loaded into an agent or subagent once, at the head of its context, and from then on stays byte-for-byte identical across sessions and spawns — so the provider's prompt cache serves it as a hit and the user never pays full price for the prefix twice. It is compiled, anchor-qualified, self-contained (resolution rules ride inside it), and deliberately front-loaded: the highest priority content reads first precisely because first is where cache stability lives.

07INDEX.md — манифест, а не содержимое. Каждая запись называет файл и говорит, статический ли он, то есть читается напрямую, или динамический — включение, которое агент разрешает по ходу. Запись может нести условие; тогда агент читает её, только когда условие выполняется для текущей сессии, например для одной операционной системы.

08 INDEX.md — a generated TOML manifest of the rest of the sequence: a schema version, a static pointer (the path of STATIC.md, when one exists), and an ordered list of [[entry]] tables. Each entry carries path, kind ("static" — a resolved file the agent reads directly; "dynamic" — an INCLUDE the agent resolves at boot, §2.4), and, for dynamic entries, when (the activation condition, §2.4). The manifest is flat and machine-precise — vibe performed the graph walk once at generation time; the agent parses one TOML document and reads the listed files, with no recursion, discovery, or cycle-detection.

Откуда берётся список

09Каждый пакет может внести один стартовый фрагмент: короткий текст, который читается при каждом старте сессии. Пакет объявляет его в своём манифесте с категорией, а манифест проекта решает, как фрагмент связан: вкомпилирован в приоритетную полосу или перечислен в INDEX.md и читается по требованию. Выбор проекта сильнее предложения пакета.

10 Decision. Each dependency declares an inclusion type, set by the consumer in its vibe.toml on the [requires.packages] entry:

11link = "dynamic" — умолчание: вклад становится путём в INDEX.md, читается по требованию и ограничен условием when, если фрагмент его объявляет. link = "static" вкомпилирует текст в приоритетную полосу, читаемую первой и целиком; им пользуются скупо, потому что он дублирует текст на диске.

12 link = "dynamic" — the default. vibe resolves the contribution to a concrete path in INDEX.md; the agent reads it dynamically, on demand. An optional when condition gates the read: with a when it is a conditional INCLUDE (loaded only when the condition holds) — mechanically the subskill lazy-pull delivery mode; without one it is read unconditionally. The when draws on the subskill [activation] probe vocabulary (PROP-003 §2.5) — one probe grammar across both mechanisms. v1 implements the os: probe end-to-end — when = "os:windows" matches the session's operating system (windows / macos / linux); the remaining probes are reserved until PROP-003's activation engine is built.

13 link = "static" — the contribution's boot text is compiled into STATIC.md ahead of time (whole, anchor-qualified — §2.3). Read first, one read, maximum attention weight. The emergency priority lane — for top-level skills and critical disciplines whose priority must be guaranteed by position, not by trusting agent-side resolution. Used sparingly; it duplicates the text on disk.

14Тип связи принадлежит ребру: его объявляет потребитель, и он никогда не впечатан в пакет. Голый static — это static-soft: пакет, статически связанный несколькими потребителями, компилируется один раз в общее место, и каждый на него ссылается. static-hard вкомпилирует его в собственную полосу каждого потребителя. static-transitive делает статическими пакет и всё его поддерево, перекрывая динамические рёбра внутри. Каждый пакет в дереве зависимостей несёт собственные стартовые файлы: то, что в него вкомпилировано, и то, на что он ссылается динамически; корень проекта — один такой пакет среди многих.

15 Decision. link is a property of the edge (consumer-side, declared in the parent's manifest), never baked into the pulled package (as PROP-034 §2.1 already states). A unit P is compiled by walking its own direct edges P→X:

16 static-soft — the default, the meaning of a bare link = "static". Hoisting dedup at compile time: a package statically linked by more than one consumer is hoisted to a shared location (§2.4) and linked once; each consumer references it. Deterministic; does not depend on read-time behaviour.

17 static-hard — explicit opt-in (link = "static-hard"). Pure local compilation: every consumer compiles the package into its own STATIC.md independently, with no hoisting. Duplication is deduplicated at read time by the read-set (§2.9).

18 static-transitive — X and its entire subtree are forced static, ignoring any dynamic edges inside — "rewrite the whole tree under X". This is the one mode that overrides nested breaks.

19 Decision. Every package materialised under vibedeps/ carries its own boot artifacts — vibedeps/<slot>/spec/boot/STATIC.xml (what is compiled into this unit, verbatim) and .../INDEX.md (this unit's external dynamic references, resolved when the unit loads) — not only entry-point workspace nodes.

20vibe вычисляет последовательность для каждого проекта из разрешённого графа зависимостей: основа, которую объявляет сам проект, затем его собственный стартовый текст, затем фрагменты его зависимостей, причём зависимость идёт раньше того, что от неё зависит. Авторы не нумеруют свои фрагменты, и два пакета не могут драться за позицию, потому что порядок выводится, а не объявляется.

21 Within the computed sequence the order is: foundation → the node's own → dependency boot (topologically — a dependency before its dependents) → user-override. static contributions are concatenated into STATIC.md in the same relative order.

Почему она короткая

22За каждое слово в полосе платят при каждом старте сессии, каждым агентом, который открывает проект. Поэтому полоса держит инструкции, а не объяснения: что делать, где правила, какие адреса цитировать. Всё, что агенту нужно лишь иногда, включая это руководство, остаётся вне полосы и берётся по адресу, когда возникает вопрос. Текст стартового фрагмента нарочно пишется под этот бюджет.

23 Everything is layered by mutation frequency — the whole loaded context is one monotone gradient (owner, 2026-08-23, near-verbatim: «всё в приложении устроено слоями; на самой вершине — динамическая загрузка быстрых изменений»). Reading order equals stability order: the rarest-changing text reads first, because a change at depth N re-prices every byte after it — the earlier a layer sits, the more cache its mutation burns. The concrete gradient: (0) the instruction files (CLAUDE.md / AGENTS.md / GEMINI.md) — read first, so an edit there resets the ENTIRE cache; they carry only what must hit every session (the four rules, the standing directives) and change only for large causes, everything else living in specs loaded later; (1) the generated STATIC lane — structural-events-only (§3), and INTERNALLY sorted by the same law: contributions of rarer-changing packages belong earlier in the tape; (2) the INDEX manifest and the conditional dynamic lane — per-boot variability; (3) the live session tail — task text, tool results, fast state, which lives in context and is never compiled into any lane. This is a GLOBAL architectural idea for all of VibeVM, not a spec of any one mechanism (owner, 2026-08-23): whenever a new system is designed or an existing one changed, the design review checks it against this layering — where does each byte it adds sit on the gradient, and does anything fast-changing sneak ahead of anything slow.

24Один и тот же префикс служит каждому агенту: когда босс и его воркеры загружают одну побайтно одинаковую полосу, кэш, который прогрел один из них, служит всем остальным. Вот почему в неё не может попасть ничего посессионного или поагентного: ни имён, ни идентификаторов, ни меток времени.

25 The multiplier: one prefix, every agent. When the boss and all its workers load the SAME byte-identical prefix, the cache warmed by any one of them serves every later spawn — each subagent starts cheap. This makes the stability requirement STRICTER than per-session determinism: nothing per-session and nothing per-agent may enter the prefix — no agent names, no session ids, no roles, no timestamps. Per-agent material belongs after the prefix, in the variable tail.

Особые случаи и правила

26Фрагмент, объявляющий условие, всегда остаётся динамической записью, какой бы тип связи ни просил проект: условие нельзя вычислить заранее, а значит, текст нельзя вкомпилировать в приоритетную полосу.

27 A [boot_snippet] that declares a when condition (§2.6) stays a conditional dynamic entry, irrespective of link: a condition cannot be honoured by the ahead-of-time static lane, so a when forces the gated INDEX form. It is a correctness constraint, not a preference — OS-specific content must never reach a session on the wrong OS.

28Цикл среди требований — жёсткая ошибка при генерации полосы, с указанием виновного пути; полоса никогда не записывается связанной наполовину.

29 Reject cycles. requires is expected acyclic; a cycle is a hard error at generate time, reported with the offending cycle path. The boot is never emitted half-linked. (This is the one place cycle detection lives; the agent-side read is a flat, recursion-free parse per PROP-009 §2.)

30Сгенерированная полоса никогда не бывает целью цитаты. Правила цитируют по адресу их исходного документа, никогда по их месту в STATIC.md, потому что полоса — вывод компилятора и меняется всякий раз, когда меняется набор зависимостей.

31 A generated STATIC.md is not a citation target — authored text never cites spec://…/boot/STATIC#…; the lane is compiler output, and source-of-truth is the package source under vibedeps/ (PROP-035 §11's lint, B-011 §6.1).

32Документация в полосу не попадает никогда. У пакета документации по определению нет стартового фрагмента; агент добирается до этого руководства через навык или по адресу, когда оно ему нужно.

33 No documentation page enters STATIC.xml, INDEX.md or a boot snippet. A doc package has no [boot_snippet]; agent-audience text is never in a boot prefix.