Skip to main content

0037: Package The Practitioner Kernel Separately

Status: Accepted

Date: 2026-07-22

Context​

STAGE already distinguished its small Practitioner Kernel from the repository's Maintainer Laboratory, but the Codex marketplace still pointed at the repository root. A local installation therefore copied the entire repository into Codex's versioned plugin cache, including Git history, a Python virtual environment, tests, trials, schemas, profiles, scripts, and maintainer documentation.

The installed 0.5.0 cache measured 69,512 KiB on the owner's machine. The files Codex actually needs at runtime--the plugin manifest and three skills--measure 60 KiB in the repository. The conceptual boundary was not reflected by the distribution boundary.

Codex local marketplace metadata selects a plugin directory but provides no package-ignore mechanism. Keeping the repository root as the package source would therefore continue to ship the laboratory. Maintaining a second generated distribution tree would introduce duplicate sources and release drift.

Decision​

  • Make plugin/ the physical installable package.
  • Keep only .codex-plugin/, operational skills, and their skill-local references inside that package.
  • Point the repository-local marketplace at plugin/ rather than the repository root.
  • Keep skills self-contained. They may link to sibling packaged skills and references, but they must not require maintainer documentation outside the package.
  • Keep normative specification, rationale, schemas, tests, profiles, studies, scripts, and release machinery in the repository laboratory.
  • Validate the package boundary: only approved top-level directories, no upward maintainer-document links, and a conservative size ceiling.
  • Do not create a generated package copy. The files under plugin/ are the canonical plugin sources.

Consequences​

  • A local Codex installation receives the procedures it executes without copying the maintainer laboratory or repository history.
  • Package size becomes an observable contract rather than an accidental consequence of repository growth.
  • Skills repeat the minimum stable operational rule they need instead of assuming access to extended rationale in docs/.
  • Maintainer documentation can evolve without silently becoming a runtime dependency of installed skills.
  • Moving a rule into maintainer-only documentation can break an operational skill unless the package tests cover that rule; focused routing tests remain necessary.
  • Repository links to skill sources now use the plugin/skills/ path.

Boundary​

This is packaging evidence for STAGE's own Codex implementation. It does not make plugin installation a requirement of the Practitioner Kernel, prescribe a repository shape for games, or prove that every agent platform needs the same distribution boundary.

Last updated on