Bridge a repository you do not own

What happens

03The agent scaffolds the package with vibe init package, marks it as a bridge in the manifest, and declares the upstream repository as an embedded source: its public address, the exact commit, the hash of the source tree and the upstream licence. Installing the package fetches that exact source into the consumer's machine store beside the package's own files. The bridge never becomes a second package: the wrapped repository is git content the resolver knows nothing about.

04 A 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.

05 [package].bridge = true marks a package as a bridge.

06 Either way, the embedded repo is not a second vibevm package: it is git content, never entered into the dependency resolver (PROP-002: one git repo = one package; the submodule is part of this package's content, not a node).

Three ways to hold the upstream

07Vendored: you copied the upstream tree into the package and committed it. This is the cheapest bridge, plain files and the flag, with hooks if the layout needs shaping. Submodule-backed: your workspace references the upstream through a git submodule, which a direct git install preserves live and which publication flattens into ordinary files. Reference-backed: the package repository holds only your metadata and adapters, and [[embedded_source]] names the upstream address, an immutable commit, the source-tree hash and the licence; installation fetches that exact source.

08 Vendored ("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.

09 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.

10 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.

[package]
name = "spec-kit"
group = "org.example"
kind = "flow"
version = "0.1.0"
bridge = true
license = "UPL-1.0"

[[embedded_source]]
name = "spec-kit"
url = "https://github.com/example/spec-kit"
commit = "0123456789abcdef0123456789abcdef01234567"
content_hash = "sha256:…"
upstream_authors = ["The Spec Kit contributors"]
upstream_license = "MIT"

12A declared source is authenticated twice when it arrives: the checkout must be at the declared commit, and the hash of its tree must equal the declared one. A ref_hint such as a tag name is only for people to read and never chooses bytes.

13 dependency-declared — a package's manifest uses [[embedded_source]] to name an upstream Git source independently of the package repository. The declaration carries a portable name, public credential-free HTTPS URL, full immutable commit, expected sha256: source-tree hash, optional ref hint, and upstream licence provenance. This supports snapshot/binary-distributed bridge packages without copying the upstream tree into their repository.

14 A dependency-declared source is authenticated twice: its resolved checkout must equal the declared commit and its deterministic source-tree hash must equal content_hash. ref_hint is diagnostic only and never selects bytes.

Whose work it is

15authors in the manifest names the people who wrote the bridge, its metadata and adapters, never the authors of the wrapped bytes; every embedded source records its own upstream_authors, and listings, locks and indexes keep the two lists apart. The same for licences: license describes the bridge alone, each source records its upstream licence and an immutable link to it, and a bridge never presents upstream bytes as relicensed. The coordinate names the product a consumer installs, not the codebase the packaging was written in: a bridge of Spec Kit may live at org.speckit/speckit whoever maintains it.

16 [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.

17 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.

18 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.

Submodules on the way in and out

19vibe fetches a package's submodules when it fetches the package, updates them with it, and makes their content available wherever the package lands: copied into the snapshot for the copying modes, live for an in-place checkout. Publication is the boundary: a registry repository is a self-contained snapshot, so the publisher checks that every populated submodule is at its indexed commit and clean, copies its files in, removes .gitmodules and reports what it flattened.

20 vibevm fetches a package's submodules when it fetches the package, updates them when it updates the package, and makes the submodule content available wherever the package is materialised — embedded into the snapshot for the copy-based modes, or living natively for in-place (PROP-022).

21 Publication boundary. Workspace/direct Git source acquisition may carry real submodules, but a per-package registry repository is a self-contained package snapshot. Publish inspects each populated gitlink before copying, requires its checkout to match the indexed commit and be clean, copies its files as ordinary payload, drops .git and .gitmodules, and reports the path plus exact vendored commit. Registry consumers therefore fetch no hidden second repository; resolved_commit identifies the published package repo, while the publication report preserves the flattened upstream evidence.

Edge cases and rules

22A bridge is published and installed like any package; what it adds is provenance. The upstream can move on without you: bumping the bridge means changing the declared commit and hash, and publishing a new version.