Skip to content

ADR-0017: Product and Component Governance Moves to Venture Repositories

Status

approved — decided directly by the Founder on 2026-07-27.

Date

2026-07-27

Context

ADR-0014 settled that venture implementation code lives in a separate, venture-owned repository. It did not settle where a product's specification, registry status, backlog, or reusable-component content live once that implementation repository exists. In practice, this repository (devonshire-digital) kept scaffolding for all of that under ventures/<slug>/:

  • ventures/digital-products/products/<slug>/ — a 19-file per-product specification scaffold, of which only 2 files (out of 19, for the venture's one real product) ever held non-template content.
  • ventures/digital-products/components/ — a 24-row "component catalog" of proposed, entirely unbuilt reusable patterns, plus per-category placeholder subdirectories.
  • ventures/digital-products/portfolio/product-backlog.md — 28 candidate product ideas.
  • portfolio/product-registry.json (top-level, cross-venture) — empty; the intake process (portfolio/intake-and-stage-gates.md) called for registering a product here "once approved for specification work," which never happened even for the venture's shipped product.
  • ventures/shelfery/product/ — the identical pattern for the Shelfery venture: a 7-file specification scaffold, entirely unfilled placeholder content, with its own implementation repository's docs/ai/ already holding the real, current product knowledge.

Both ventures' real product content already lived in their own implementation repositories (devonside-labs, shelfery) in practice — the governance-repo scaffolding had become dead weight duplicating (or, more often, simply failing to duplicate) content that already existed elsewhere. devonshire-digital's own docs/architecture/company-venture-product-model.md still described this scaffolding as the intended home for "Product" and "Component" layer content, which no longer matched how either venture actually worked.

The Founder's direct instruction: this repository's governance should end at the venture — its name, purpose, scope, and potential markets, and (per this ADR's own follow-on decision the same day) its legal structure. Everything about what a venture actually builds — specifications, decisions, registry/lifecycle status, backlog, reusable patterns — belongs in that venture's own implementation repository.

Decision

  1. Per-product specifications, decisions, and registry records live entirely in the venture's implementation repository, not under ventures/<slug>/products/ here. This extends DD-DIGPROD-ADR-0003 (which moved specification content for Digital Products specifically) to every venture and to registry/lifecycle status as well, not specification content alone.
  2. Each product's product.json (id, slug, lifecycle_status, version, owner, status_note, and pointers to that product's real docs) lives with the product, in its implementation repository. This is the authoritative registry record.
  3. This repository's top-level portfolio/product-registry.json becomes a pure, combined table of contents — a mirror of every venture repository's product.json files, carrying no independent governance judgment of its own. It answers "what products exist across the company," not "what stage is this product actually at" — that answer lives only in the product's own product.json. Keeping it in sync is the responsibility of whoever creates or updates a product in a venture repository (see Follow-up Actions).
  4. Product backlogs (unbuilt candidate ideas) live in the venture's implementation repository, not here. A venture's scoring methodology and cross-cutting research-question tracking remain here, since those are venture-level process concerns, not product content.
  5. This repository does not maintain a speculative component catalog. Digital Products' 24-row, entirely-unbuilt catalog is retired outright (status: deprecated, not deleted, per the archival-and-retention standard) rather than migrated — nothing in it was ever built, and the venture's real product already bypassed it, building its own patterns directly and promoting one to a shared module only once a second product needed it. That build-then-promote flow, documented in the venture's implementation repository, is the reuse mechanism going forward for any venture. docs/standards/component-specification-standard.md (the rule for how a component spec should be written, if one is ever written) is unaffected by this — it is a standard, not product/component content, and survives per point 6.
  6. Company-wide, content-agnostic standards stay here. docs/standards/product-specification-standard.md's 16 required baseline sections remain governance-repo policy — they define what any product specification must cover, wherever it lives, not the specification itself. The same logic applies to any other standard that constrains product or component content without being that content.
  7. ventures/shelfery/product/ is retired the same way, for the same reason: its 7 files hold no content beyond what Shelfery's own implementation repository (shelfery, formerly pantryplus) already documents in docs/ai/.

Consequences

  • Benefit: removes the standing duplication/drift risk this ADR's Context section describes — one authoritative location per product, not a governance-repo scaffold plus a venture-repo reality that may or may not match it.
  • Benefit: matches actual behavior instead of leaving stale gate descriptions on record — company-venture-product-model.md, intake-and-stage-gates.md, and the venture-repo creation template are all updated in this same change (see Follow-up Actions) so a fresh reader isn't misled about where product work happens.
  • Cost: this repository can no longer be audited alone for product-specification or component-catalog compliance — that now requires opening each venture's implementation repository. portfolio/product-registry.json mitigates this partially (a company-wide index still exists here) but is only as current as whoever last synced it from a venture repository.
  • Cost: the venture-repo creation template (templates/implementation-repository/) gains a new responsibility (product registration instructions) that has to be kept current as this pattern is used for future ventures, or it will drift the same way the scaffolding it replaces did.
  • This does not change anything about company-level or venture-level policy, brand, or strategy content — only per-product and per-component content. The distinction this ADR draws (venture existence vs. venture output) is the same distinction the Founder stated directly when resolving this.

Alternatives Considered

  • Keep the governance-repo scaffolding and require it be kept filled in. Rejected: this is the status quo that produced the drift described in Context — 19 files with 2 ever filled in, for the venture's only shipped product, over two weeks of active building. There's no evidence keeping the requirement would change actual behavior going forward.
  • Migrate the component catalog into the venture repository instead of retiring it. Rejected (Founder's explicit call, following clarification of what it actually contained): nothing in it was ever built, and it was already being bypassed by the mechanism that actually works (build once, promote once proven). Migrating a catalog nobody uses just relocates the dead weight rather than removing it.
  • Scope this ADR to Digital Products only, leaving Shelfery's identical stub folder in place. Rejected (Founder's explicit call): the underlying architecture document this ADR revises applies to both ventures, and Shelfery's product/ folder is in the exact same all-stub state Digital Products' was. Leaving one venture's copy in place after establishing the pattern doesn't apply would just recreate the same "governance repo says something the venture repo contradicts" problem this ADR exists to close.

Follow-up Actions

  • Rewrite docs/architecture/company-venture-product-model.md's Product and Component layer descriptions to match this decision, and fix its stale reference to the (superseded) ADR-0007 implementation-repository boundary as still "open."
  • Rewrite portfolio/intake-and-stage-gates.md's product-registration step to point at the venture repository, not portfolio/product-registry.json directly.
  • Update templates/implementation-repository/ (the scaffold scripts/create_implementation_repository.py uses for every new venture repo) to bake in: (a) a product.json convention per product, and (b) an instruction to keep this repository's portfolio/product-registry.json table of contents in sync when a product is created or its status changes.
  • Reduce portfolio/product-registry.json to the table-of-contents framing and populate it from devonside-labs' two products' product.json files.
  • Retire ventures/digital-products/components/component-catalog.md (status: deprecated) and remove its now-purposeless empty category subdirectories; rewrite ventures/digital-products/components/README.md accordingly.
  • Remove ventures/digital-products/products/llc-accounting-tracker/ and products/_template/, after migrating the two files that held real content into devonside-labs (done as part of this same change).
  • Remove ventures/digital-products/portfolio/product-backlog.md, after migrating it verbatim into devonside-labs' docs/ai/product-backlog.md (done as part of this same change).
  • Remove ventures/shelfery/product/ (pure removal — verified zero non-template content first).
  • Fix every cross-reference to the removed/relocated paths found across both ventures' documentation (done as part of this same change; see the commit this ADR ships with).

Report an issue about this page