PVD - Product Vision Document (larger projects)

Most vibe-coding and spec-driven tools assume one repo, one product. Real products are rarely that tidy - a web app, an API, a mobile backend and a shared library can be one product to a customer and four repositories to the team. The Product Vision Document is the layer above the PRD that holds that product together with a centralised vision.

Note

A single repo never needs a PVD - its PRD is the top of the tree. Reach for a PVD when several repos form one product: shared features, an inter-repo API, coordinated releases - and the coordination is currently living as stale prose in review notes and handovers.

What it is

The PVD coordinates and traces - it never re-specifies. It does not restate any feature; it points at the per-repo PRD that owns the spec. There is one writable master, read-only everywhere else, kept honest by a projection that fails loud if it drifts.

• One writable master: sdlc-studio/product/pvd.md, in a product (anchor) repo, owned by the Product Manager persona - distinct from the Product Owner who owns each repo’s PRD.
• The manifest: sdlc-studio/product/manifest.yaml lists each child repo by short id, local path and git URL. It is a coordination manifest, not a hard dependency: a repo that is not on disk yields an unresolved marker rather than a silent pass.
• The feature map: in the master, each product feature PF#### maps to its owning repo and the CR / RFC / PRD artefact that lands it.

The workflow

/sdlc-studio pvd create     # render the tiered master into the product repo
/sdlc-studio pvd sync       # project the master read-only into each child repo
/sdlc-studio pvd drift      # fail loud if a child projection has gone stale

1. pvd create renders the master into sdlc-studio/product/pvd.md.
2. List each repo in manifest.yaml.
3. Map each PF#### to its owning repo and the artefact that delivers it.
4. pvd sync projects the master read-only into every child repo (a symlink in production, a synced copy in development); pvd drift is the standing seam-check that fails if a projection goes stale.

Proportionality: two tiers

• Lean (always): vision & scope, strategic goals, the master feature inventory, cross-repo dependencies, API contract commitments, a risk & conflict register, and a decisions log.
• Opt-in (large multi-team products only): the master / domain / team PVD topology tree, G1–G5 governance stage-gates, and formal release coordination. Delete what you do not use - the tool does not want you carrying empty ceremony.

Caution

The feature map is reviewed by humans in the normal review cadence, not machine-checked - an automated cross-repo traceability check was tried and deliberately retired. The PVD makes the coordination visible and owned; it does not pretend to prove it.

PVD vs the project command

Do not confuse the two. The project command is single-repo orchestration - it builds a dependency graph of one repo’s epics and drives them to done in order. The PVD is the multi-repo layer - coordinating the separate products that together form one. Different scope, different jobs.

Where to next

• PRD - the per-repo document the PVD coordinates but never restates.
• The specification layer - how the PVD sits above PRD / TRD / TSD.
• Sprint planning - how each repo’s own backlog becomes sprints.