Skip to content

Workspace Layout

The repository layout is intentionally direct so maintainers can see where a concern belongs before they open any code. The directory tree is part of the design language: it should reinforce the package split instead of making it harder to see.

These repository pages should explain the cross-package frame that no single package can explain alone. They are strongest when they make the monorepo easier to understand without turning the root into a second owner of package behavior.

Visual Summary

graph TD
    A[Change request] --> B{Scope}
    B -- Package-local --> C[packages/<owner>]
    C --> D[Package tests and docs]
    B -- Cross-package --> E[Root orchestration]
    E --> F[Makefile and makes]
    E --> G[apis and workflows]
    D --> H[Reviewable result]
    F --> H
    G --> H

Top-Level Directories

  • packages/ for publishable Python distributions
  • apis/ for shared schema sources and pinned artifacts
  • docs/ for the canonical handbook
  • makes/ and Makefile for workspace automation
  • artifacts/ for generated or checked validation outputs
  • configs/ for root-managed tool configuration

Layout Rule

A concern should live at the root only when it serves more than one package or when it is about the workspace itself.

Concrete Anchors

  • pyproject.toml for workspace metadata and commit conventions
  • Makefile and makes/ for root automation
  • apis/ and .github/workflows/ for schema and validation review

Use This Page When

  • you are dealing with repository-wide seams rather than one package alone
  • you need shared workflow, schema, or governance context before changing code
  • you want the monorepo view that sits above the package handbooks

Decision Rule

Use Workspace Layout to decide whether the current question is genuinely repository-wide or whether it belongs back in one package handbook. If the answer depends mostly on one package's local behavior, this page should redirect instead of absorbing detail that the package should own.

What This Page Answers

  • which repository-level decision this page clarifies
  • which shared assets or workflows a reviewer should inspect
  • how the repository boundary differs from package-local ownership

Reviewer Lens

  • compare the page claims with the real root files, workflows, or schema assets
  • check that repository guidance still stops where package ownership begins
  • confirm that any repository rule described here is still enforceable in code or automation

Honesty Boundary

These pages explain repository-level intent and shared rules, but they do not override package-local ownership. They also do not count as proof by themselves; the real backstops are the referenced files, workflows, schemas, and checks.

Next Checks

  • move to the owning package docs when the question stops being repository-wide
  • check root files, schemas, or workflows named here before trusting prose alone
  • use maintainer docs next if the root issue is really about automation or drift tooling

Purpose

This page provides the shortest file-system map for the repository.

Stability

Keep this page aligned with the real root directories and remove any mention of retired roots.