Skip to content

Venture Implementation Repository Default (GitHub Issue #1)

Objective

Generalize the multi-repository pattern already proven by Shelfery/pantryplus (ADR-0010) into company-wide policy — venture implementation code lives in its own repository by default — and build scaffolding tooling so a new venture implementation repository can be created consistently when a venture reaches implementation stage.

Scope

  • Draft ADR-0014, superseding ADR-0007, recording the general policy: venture implementation code lives in a separate repository per venture; brand/asset creation stays centralized in devonshire-digital; finished assets are transferred to venture repos as needed.
  • Update docs/decisions/README.md's ADR index (also backfilled missing ADR-0011/0012/0013 entries found stale while updating it).
  • Update docs/governance/repository-boundaries.md and docs/architecture/future-repository-strategy.md so they describe the resolved default instead of an open question, per ADR-0014's own follow-up actions.
  • Build templates/implementation-repository/ — a directory skeleton (AGENTS.md, CLAUDE.md, README.md, docs/ai/ knowledge base with index, .github/workflows/ci.yml, .gitignore) modeled on the actual structure of pantryplus (inspected directly at C:\Users\Stuart\repos\pantryplus), generalized to be stack-agnostic beyond that structural pattern.
  • Build scripts/create_implementation_repository.py, mirroring scripts/create_venture.py's conventions, to scaffold a new venture implementation repository from that template. Does not run git init, create a GitHub repository, or push anything — those remain deliberate human steps.
  • Exempt templates/implementation-repository/ from this repository's document-metadata validation (scripts/validate_metadata.py), since its content is scaffolding for a separately governed repository that doesn't use this repository's front-matter conventions (matching the reference pattern, pantryplus, which carries none).
  • Update scripts/README.md and templates/README.md indexes to list the new script/template.

Out of scope

  • Issue #2 (Human Review and Approval policy) — completed separately, see work/archive/2026-07-12-human-review-approval-policy-update.md.
  • Issue #3 (Shelfery food-safety claims ADR) — separate task.
  • Actually creating a new venture implementation repository on GitHub. This task builds the tooling; running it for a real venture (e.g. Digital Products, once it has implementation work) is a future, separate action.
  • Resolving Digital Products' own unresolved registry status — that venture still has no implementation work, so ADR-0014 establishes the pattern it will follow, not an actual repository for it today.
  • Automated brand-asset syncing between this repository and venture implementation repositories (ADR-0014 notes this as a standing manual/scripted risk, not something this task builds).

Applicable authority

  • ADR-0007 — superseded by this work's ADR-0014.
  • ADR-0010 — the precedent this decision generalizes from.
  • ADR-0005 — brand centralization consistency.
  • docs/governance/repository-boundaries.md, docs/architecture/future-repository-strategy.md.
  • CLAUDE.md — ADR required for material/hard-to-reverse architecture decisions; status stays proposed until the Founder explicitly ratifies it, naming the document.

Files expected to change

  • docs/decisions/ADR-0014-venture-implementation-repositories-are-the-default-pattern.md (new)
  • docs/decisions/README.md
  • docs/governance/repository-boundaries.md
  • docs/architecture/future-repository-strategy.md
  • templates/implementation-repository/** (new directory)
  • scripts/create_implementation_repository.py (new)
  • scripts/validate_metadata.py
  • scripts/README.md
  • templates/README.md

Assumptions

  • The issue's intent generalizes ADR-0010's Shelfery-specific outcome rather than establishing a different policy for future ventures; there's no indication in the issue or prior ADRs that a future venture should default to monorepo.
  • "Brand development and asset creation will stay in this repository" (issue #1's own wording) is consistent with, and doesn't require changing, ADR-0005's existing brand-independence architecture — treated as reinforcement, not a new brand decision.
  • The scaffolding tool's CI/stack defaults (Node/npm, per pantryplus) are a reasonable starting point to delete/replace, not a mandate — documented explicitly in the template's own comments so a non-Node venture doesn't inherit them silently.

Risks

  • Classified as an architecture/policy decision (ADR) — moderate/high-risk per task-classification-and-routing.md — requires Founder sign-off before status can move past proposed.
  • Risk that the scaffolding tool goes stale relative to whatever conventions this repository (or pantryplus) evolves next, since nothing enforces the two staying in sync — noted as a named consequence in ADR-0014 itself, not solved by this task.
  • Pre-existing drift noticed (not fixed, out of scope): schemas/repository.schema.json documents a path_or_url field, but actual portfolio/repository-registry.json entries use separate path/url fields. The new script follows the actual data convention (path/url) for consistency with existing entries rather than the unenforced schema. Flagging here per editing discipline rather than fixing inline.

Validation plan

  • python scripts/check.py — all validators.
  • python -m unittest discover tests — full suite.
  • Manual smoke test of scripts/create_implementation_repository.py against a scratch directory: verified placeholder substitution, refusal to write inside this repository, and refusal for an unregistered venture slug.
  • Human review/approval of ADR-0014 before its status moves past proposed.

Progress checklist

  • [x] Reviewed ADR-0007, ADR-0010, repository-boundaries.md, future-repository-strategy.md, portfolio/repository-registry.json.
  • [x] Inspected pantryplus (local clone at C:\Users\Stuart\repos\pantryplus) as the reference structural pattern.
  • [x] Drafted ADR-0014 via the new-adr skill; updated the ADR index.
  • [x] Built templates/implementation-repository/ and scripts/create_implementation_repository.py.
  • [x] Exempted the new template subtree from validate_metadata.py.
  • [x] Updated repository-boundaries.md and future-repository-strategy.md for consistency.
  • [x] Updated scripts/README.md and templates/README.md.
  • [x] Ran python scripts/check.py (all checks passed) and python -m unittest discover tests (38 tests, OK).
  • [x] Smoke-tested the new script (success case + two guardrail failure cases).
  • [x] Presented to user. User explicitly approved ADR-0014, naming the document, 2026-07-12. Set status: approved, approved_by: Stuart M. Davis (Founder), approved_date: 2026-07-12, effective_date: 2026-07-12.
  • [x] Updated referenced ADRs for consistency: ADR-0007 set to status: superseded (superseded by ADR-0014), cross-referenced; ADR-0010's consequences section corrected (it previously said ADR-0007 was "not superseded in full" — now superseded in full by ADR-0014); ADR index (docs/decisions/README.md) marked ADR-0007 superseded.
  • [x] Re-ran python scripts/check.py (all checks passed) and python -m unittest discover tests (38 tests, OK) after the approval edits.
  • [x] Closed GitHub issue #1.
  • [x] Archived this plan.

Decisions required

  • Founder must review and explicitly approve ADR-0014 (naming the document) before its status can move to approved.
  • Whether to run the new scaffolding tool for any real venture now, or leave it unused until Digital Products (or a future venture) actually reaches implementation stage.

Handoff notes

All file changes are complete and validated as of this session. If picked up later: ADR-0014 is still status: proposed — check whether Founder approval has since been recorded before assuming it's binding policy.

Report an issue about this page