Planes

draft 1.0.0
  status experimental
  title Planes Specification
  date 2026-03-08
  license All Rights Reserved

---

spec planes

  section purpose
    title Purpose
    level 1

    prose
      value
        Planes makes the implicit explicit: a repository's source
        is not one undifferentiated mass but a small number of
        functional planes (code, ops, data). Planes declarations
        let a tool find each plane without guessing — and let a
        repository's directory structure evolve without breaking
        downstream tools that knew where to look.

  section declarations
    title Plane declarations
    level 2

    prose
      value
        Planes are declared in package.json under the byre block,
        in the @byre/planes member, by mapping each plane name
        to the directory it lives in.

    requirement P-001
      level MUST
      value
        A repository adopting planes MUST declare at least one
        plane in its package.json under byre['@byre/planes'].

    requirement P-002
      level SHOULD
      value
        Repositories SHOULD declare a code plane pointing at the
        directory containing source files (typically src/).

  section plane-vocabulary
    title Plane vocabulary
    level 3

    prose
      value
        The initial recognised planes are code (source), ops
        (operations: build, deploy, lint, test orchestration),
        and data (content). New planes can be proposed by
        consumers without breaking existing tools.

  section example
    title Example — byre.dev
    level 4

    prose
      value
        byre.dev declares code: src under @byre/planes — meaning
        all source code lives under src/. The ops plane is not
        declared because there is no separate ops tree; build
        orchestration lives at build.mjs at the repository root.