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

ADR 0004: Introduce Capability Architecture

  • Status: accepted
  • Date: 2026-07-05
  • Deciders: Azwaan
  • Tags: structure, capability-architecture

Context

The portal documented repositories, systems, and layers — but the ecosystem’s real reuse happens at the level of capabilities that span multiple repositories. The Website Assessment Platform made this obvious: it is one capability provided by four repos (inexisstudios engine, intelproducts pack, personalops authoring, website-intelligence-lab harness) and consumed by others. Documenting only repos hid both the capability and its reuse/duplication characteristics (e.g. two parallel opportunity-scoring models).

Decision

We will:

  1. Add a first-class Capability Architecture section (portal/capabilities/) with a Capability Registry as a primary navigation entry point, and a per-capability page standard (templates/capability.template.md) recording purpose, business value, technical responsibilities, owners, consumers, ventures, inputs/outputs, dependencies, maturity, and planned evolution — independent of any single repository.
  2. Add a Capability Reuse Map documenting providers, consumers, shared assets, intelligence dependencies, reuse opportunities, and duplication risks.
  3. Document the Website Assessment Platform as a cross-repo capability with four architecture views (executive, container, component, runtime), evidence-first, with honest implemented/planned/vision labels.
  4. Keep capabilities and repos cross-linked: capability pages link to repo digests, ventures, architecture, and ADRs, and vice versa.

Options considered

Option Pros Cons
A (chosen): first-class capability architecture + registry + reuse map Surfaces reuse & duplication; matches how the ecosystem actually composes More pages to keep consistent
B: document capabilities inside repo digests only Less structure Cross-repo capabilities have no home; reuse invisible
C: capabilities as tags on repos Cheap No owner/consumer/lifecycle modelling; no reuse analysis

Consequences

  • Positive: the portal now answers “which capabilities exist, who owns/consumes them, and where is reuse or duplication” — shifting it from a repo catalogue to an architectural source of truth.
  • Negative / trade-offs: capability ↔ repo ↔ venture links multiply and must stay consistent (the orchestrator will eventually reconcile them).
  • Follow-ups / affected pages: Capability Registry, Reuse Map, Portfolio Overview, Architecture Principles (new principles 11–12), registry, dashboard, IA.

Compliance / review

Enforced by the Definition of Done in CLAUDE.md and Principle 8 (honest labelling). Revisit when the orchestrator can auto-derive capabilities from source.