BCOM GitHub Architecture

A blueprint for organizing BCOM's GitHub so that the difference between a file converter and a self-improving AI agent is baked into the folder structure itself.

The core problem this paper solves is categorical confusion. BCOM builds everything from tiny utilities to full algorithmic agents, and if you dump them all into one "services" bucket you lose the ability to reason about what a system actually is. The paper introduces a three-tier taxonomy — L1 Tools (stateless utilities), L2 Services (stateful, with dashboards, but no self-awareness), and L3 Agents (full algorithmic agents with a persona, an objective function, a self-model, and a closed feedback loop) — and proposes a six-pillar GitHub organization where each tier has its own home. The classification isn't fuzzy: four binary tests determine whether something is L3, and failing any one of them caps it at L2.

The most technically interesting contribution is the L3 Agent repo skeleton, which mirrors the "Algorithmic Agent" decomposition from WP0018. Every agent repo has directories for world model, self model, objective function, simulator, comparator, updater, and planner — one folder per cognitive module, each with a spec .md file sitting next to the code. The spec is the contract; an empty folder with only a spec is an honest gap, not a mess. This forces every new agent to answer hard architectural questions (where does the loop close? what is in the objective function?) as a side effect of creating the directory structure. The paper also introduces a "membrane" pattern for all IO: HTTP, MCP, and future surfaces like voice or robotic actuators all pass through the membrane, leaving the cognitive core untouched when new modalities are added.

The six pillars are Meta (conventions, CI, brand), Tools (L1), Services (L2), Agents (L3), Research (per-project code), and Collab (external partners). Eleven repos are scaffolded on day one from templates; everything else is created on demand. Visibility is explicitly orthogonal to pillar — any repo can be made public regardless of which pillar it lives in. The design deliberately avoids premature abstractions: no shared bcom-core, no shared infra repo, no placeholder repos for unfunded future agents.

The migration plan is four phases: scaffold the 11 repos first, then migrate Calliope (already L3, so it's mechanical relocation that validates the skeleton), then migrate Artemis (currently L2, requires new code to earn L3 status), then build Nomos and Morphe as L3 agents from scratch. The paper is honest about what's out of scope: deployment strategy, agent-to-agent communication, shared world models, and LLM cost monitoring are all explicitly deferred.