ADR-0003: Canonical Repo Structure — Four-Pillar Model¶

2026-08-02

Status¶

Proposed

Date¶

2026-08-02

Context¶

The ovesorg workspace contains 40+ repos with varying maturity levels. Agents and developers cannot reliably discover what a repo exists to do, how it accomplishes that purpose, how to deploy or operate it, and where to find adoption documentation.

Without a canonical structure, each repo invents its own documentation layout, leading to inconsistent agent discovery, redundant scanning, and lost operational knowledge.

Decision¶

Every repo in the collection SHALL organize its MCP-facing context around four canonical pillars. Each pillar maps to an existing MCP resource surface:

Pillar 1: Rationale (Why this repo exists)¶

MCP surface: docs/context/capabilities.md + repo://{repo}/capabilities

Content: - What this repo owns and does NOT own - The problem space or business need it addresses - Cross-repo boundary declarations

Pillar 2: Solution Mechanism (How it works)¶

MCP surface: docs/context/contracts.md + repo://{repo}/contracts

Content: - Architecture, design rules, and invariants - Authority order and governance - Schema, API, or integration contracts - Cross-repo compatibility rules

Pillar 3: Deployment Instructions (How to operate it)¶

MCP surface: docs/context/workflows.md + repo://{repo}/workflows

Content: - Operational paths for agents and developers - Build, deploy, test, and provisioning commands - Local development and review conventions - CI/CD pipeline documentation

Pillar 4: Documentation and Training (How to adopt it)¶

MCP surface: docs/agent/start-here.md + repo://{repo}/start-here

Content: - Reader-first onboarding path - Navigation structure (Home → reader sections → Reference) - Training materials and adoption guides - Links to external resources

Structural Rules¶

All four pillar files MUST exist in every repo that participates in the workspace MCP (i.e., every repo with docs/agent/manifest.yaml).
Each pillar file MUST be repo-specific, not a generic placeholder.
The MCP server already exposes all four pillars as repo:// resources; this ADR makes the content contract mandatory rather than optional.
The mcp_provision.py script MUST generate pillar-aligned content for new repos and flag missing pillar content for existing repos.
The mkdocs-template init/normalize workflow MUST scaffold these four files when bootstrapping a new repo.

Discovery Contract¶

Workspace-level discovery (list_repos, resolve_repo_context) SHALL return the four pillar surfaces as part of every repo's declared context so agents can route to the right pillar without blind scanning.

Nav Integration¶

The mkdocs-template nav baseline SHALL include the four pillars as a standard "Agent Context" section:

nav:
  - Home: index.md
  - ...
  - Agent Context:
    - Start Here: agent/start-here.md       # Pillar 4
    - Capabilities: context/capabilities.md  # Pillar 1
    - Workflows: context/workflows.md        # Pillar 3
    - Contracts: context/contracts.md        # Pillar 2

Consequences¶

Benefits¶

Agents can deterministically discover repo purpose, mechanism, operations, and documentation without scanning the entire repo
Every repo in the workspace becomes self-describing
The four-pillar structure is already partially in place (context docs exist in many repos); this ADR formalizes the contract
Consistent structure enables batch operations (audit, provision, normalize)

Trade-Offs¶

Requires updating ~40 repo context files from generic placeholders to repo-specific content
Existing repos with non-standard structures need migration
Adds a conformance check to the provisioning and normalization workflows

Migration Path¶

Update mcp_provision.py to generate pillar-aware templates
Update mkdocs-template init/normalize to scaffold pillar-aligned files
Batch-provision all existing repos with updated pillar templates
Repo owners fill in repo-specific pillar content
Add pillar-completeness check to inventory_workspace_mcp.py