Portfolio Portal
ADR accepted owner: Azwaan reviewed: 2026-07-05

ADR 0002: Adopt the layered ecosystem model and the repo-digest standard

  • Status: accepted
  • Date: 2026-07-05
  • Deciders: Azwaan
  • Tags: structure, standards, cross-repo

Context

Phase B processed the first real repository (Shared Skills). Two things needed to be settled while doing so: (1) how the ecosystem is organized at the top level, and (2) the depth and shape every repository digest must follow. Getting these right now — on the first repo — sets the pattern for all future repos and keeps the portal consistent and automatable.

Decision

We will:

  1. Model the ecosystem as a six-layer architecture — Shared Skills → Intelligence Platform → Intelligence Products → Applications & Agents → Ventures → Customer-facing Solutions — with Shared Skills as the foundational, laterally-consumed layer. This model is documented in the Portfolio Overview and the architecture pages.
  2. Adopt an expanded repo-digest standard that captures purpose, why-it-exists, business capability, technical responsibilities, core concepts, workflows, technologies, modules, upstream/downstream dependencies, interfaces, reusable assets, decisions, maturity, roadmap, limitations, opportunities, and ecosystem relationship. The Shared Skills digest is the reference instance and templates/repo-digest.template.md encodes it.
  3. Require honest realization labelling — planned layers/systems are marked Planned/Concept and never asserted as built; assumptions and uncertainties are recorded explicitly.

Options considered

Option Pros Cons
A (chosen): layered model + rich digest standard Clear north-star; consistent, automatable digests; honest about maturity More authoring effort per repo
B: flat repo list, minimal digests Fast No system-of-systems story; weak onboarding/showcase value
C: model only realized repos, no layers Purely factual Loses the architectural vision the ecosystem is organized around

Consequences

  • Positive: every future repo digest is comparable and complete; the overview gives new engineers/investors the whole picture fast; the structure is a clean target for the orchestrator.
  • Negative / trade-offs: richer digests take more effort; the layered model includes planned layers that must be kept clearly labelled to avoid over-claiming.
  • Follow-ups / affected pages: portfolio-overview, architecture, repo-digest template, registry, IA.

Compliance / review

Enforced via the Definition of Done in CLAUDE.md and the invariants in update conventions. Revisit if the layer model changes or the digest standard proves too heavy in practice.