PROP-023 — Bridge packages

1.1 The problem — good work that nobody packaged

• 03People publish skills and projects to GitHub / GitVerse without ever making a vibevm package — out of disinterest, or because their repo's layout has nothing to do with vibevm conventions.
• That work is then unreachable through vibe install, and the original author has no incentive to change.

• 04A bridge package closes the gap without the author's involvement: a maintainer volunteers to steward someone else's repository and publishes an ordinary vibevm package that wraps it.
• The bridge makes the foreign repo consumable by vendoring it, carrying a git-native submodule, or declaring an immutable external embedded source. The reference-backed form keeps upstream bytes out of the bridge repository and fetches them directly from the author.

1.2 What this is — a thin convention over three mechanisms

05A bridge is not a new kind of package or a new subsystem. It is:

• 06an ordinary package (still one of flow / feat / stack / tool),
• carrying the foreign repo as vendored content, a git-native submodule, or a manifest-declared immutable external embedded source (PROP-021),
• optionally prepared by install hooks (PROP-020),
• optionally materialised as in-place when the upstream is a giant (PROP-022),
• with any skill projected selectively from the bridged subtree (PROP-015 #skill-include).

07…plus one flag that says "this is a bridge."

2.1 A bridge is marked by a flag, not a kind

08req r1

• 09[package].bridge = true marks a package as a bridge.
• It does not change the package's kind (a bridged skill is still a feat/tool as appropriate) or its identity.
• The flag is metadata with two jobs: it documents that the package's substantive content is foreign (stewarded, not authored, by the maintainer), and it is the hook the registry/UI uses to surface provenance (§2.4).
• Default false; the overwhelming majority of packages are not bridges.

2.2 Three classes — vendored, submodule-backed, and reference-backed

10req r1

11A bridge obtains the upstream repo in one of three ways:

• 12Vendored ("git in git") — the maintainer copied the upstream tree into the package and committed it. This needs none of PROP-021/022 machinery: it is plain files in a snapshot package. A vendored bridge is therefore the cheapest case — the flag (§2.1) plus, if the layout needs shaping, hooks.
• Submodule-backed authoring — the maintainer workspace references upstream through a Git submodule (PROP-021). A direct Git-source install preserves that live Git composition. Registry publication deliberately flattens a clean populated gitlink into ordinary package files, removes .gitmodules, and reports submodule <path> vendored at <sha>; the published package is therefore a truthful vendored snapshot, not a dangling promise that consumers will recurse into the maintainer's repo.
• Reference-backed — the package repository contains only maintainer-authored metadata and adapters. [[embedded_source]] declares the original public Git URL, an immutable full commit, an independently verified source-tree hash and upstream licence provenance. Installation fetches that exact source directly into the consumer's machine cache; selected [[skill]] content or [[skill.resource]] files are projected from the authenticated cached tree. The upstream is not copied into the bridge repository, is not resolved as a vibevm dependency node, and its own vibe.toml, hooks and submodules are never executed implicitly. The installed bridge itself remains a normal physical vibedeps slot; source-aware loaders combine that owner root with named, separately authenticated external roots without pretending the latter are UPL package payload.

13The maintainer chooses per trade-off: vendored is self-contained; submodule-backed uses Git's native composition; reference-backed preserves repository and licence boundaries but needs the pinned upstream once per machine-cache miss.

2.3 Composition — every mechanism is optional

14req r1

15A bridge is the point where the three orthogonal mechanisms compose, but it mandates none of them:

• 16a bridge without hooks is valid (the upstream layout already fits);
• a bridge without a submodule is valid (vendored);
• a bridge without in-place is the norm (in-place is only for giant upstreams).

• 17The canonical full case — submodule-backed + pre-install hook to shape the tree + selective skill projection — is the union of the four specs, but each piece is independently usable outside any bridge.
• This is why they are four specs and four test sets, not one (the owner's orthogonality requirement).

2.4 The maintainer model

18req r1

• 19The bridge's maintainer is distinct from the upstream author.
• [package].authors names only the people or organisations that authored the package's own metadata, adapters and other maintainer-owned payload. It never absorbs the authors of referenced bytes. Every [[embedded_source]] records those separately as a non-empty upstream_authors list. Listings, locks and indexes preserve both lists under their own labels; they never concatenate them into one ambiguous authorship claim.
• The package's qualified coordinate (PROP-008) names the product a consumer installs, not the codebase in which its packaging machinery happened to be written. Packaging Spec Kit does not make it org.vibevm/*; its product coordinate may be org.speckit/speckit. Packaging Matt Pocock's collection may be com.mattpocock/skills. The distinct steward remains visible through [package].authors, the package distribution source_url, bridge = true, and the upstream repository/PURL recorded by [[embedded_source]] and describes.
• A consumer can therefore see three separate answers: what product is this (coordinate), who maintains this packaging (authors + distribution source), and what original bytes does it wrap (upstream provenance).
• Not everything we package belongs to VibeVM. A third-party product's package source defaults to its own Git repository outside the VibeVM monorepository and outside org.vibevm/*. Before scaffolding a bridge, the maintainer must explicitly ask the owner whether the package belongs in an existing product workspace or should be an independent repository. Silence never authorises absorbing a foreign product into the VibeVM namespace. Locally, independent package repositories may live under a neutral collection such as ~/git/v/packages/; publication still maps one package repository to one registry repository.
• A bridge records two distinct legal surfaces: [package].license describes only the maintainer-authored bridge package, while every external embedded source records its upstream licence and an immutable licence URL. A bridge never presents upstream bytes as relicensed by the bridge maintainer.
• A skill that lives inside the bridged subtree is projected through the normal skill machinery, using the include selector (PROP-015 #skill-include) to pick the relevant files out of an upstream tree full of unrelated content.