Skip to content

Dirac Repo Standardization Intent

Status: Proposed Date: 2026-03-29 Scope: dirac-* repositories

Intent

Standardize the documentation and decision layout of every dirac-<component> repository so a workspace-wide MCP server can discover canonical and local decisions without repo-specific parsing rules.

Objectives

  • Give every dirac-* repo a predictable docs/adr entry point.
  • Separate platform-level canonical decisions from repo-local implementation decisions.
  • Make overrides explicit instead of embedding them in architecture prose.
  • Support machine-readable discovery with stable paths and metadata.

Required Minimum for Each dirac-* Repo

docs/
  adr/
    index.md
    canonical/
    overrides/

Ownership Model

  • dirac-framework owns canonical cross-repo decisions.
  • Each dirac-<component> repo owns its local ADRs and any explicit overrides.
  • Background, concepts, and implementation notes are subordinate to ADRs and must not replace them.

MCP-Facing Rules

  • Canonical ADRs must live under docs/adr/canonical/.
  • Override ADRs must live under docs/adr/overrides/.
  • ADR identifiers must be stable and unique within their intended scope.
  • Overrides must reference the canonical ADR they refine, constrain, or replace.

Rollout Sequence

  1. Create the docs/adr structure in every dirac-* repo.
  2. Convert cross-repo decisions into canonical ADRs in dirac-framework.
  3. Convert repo-local deviations into explicit override ADRs in owning repos.
  4. Move remaining narrative architecture material into background or concept sections.
  5. Add registry and validation once the folder contract is stable.

Non-Goals

  • Duplicating repo-local implementation guidance in dirac-framework
  • Treating broad architecture narrative as an ADR without an explicit decision
  • Preserving placeholder locale builds without translated ADR content