How jordansshaw-pixel/command-center-os-starter works
1. What this repo is
- Command Center OS is not a product app; it is a folder-based operating system for AI-assisted work. Its architecture is organized around durable root policy, a routing layer, a memory layer, an agent crew, and project/venture folders that inherit the framework.
2. Top-level boundary and trust model
- The repo is explicitly split into stable system law versus local project truth:
- CLAUDE.md is the canonical root identity.
- AGENTS.md is the Codex-facing entry/loader.
- _operator/ holds operator-specific truths.
- _routing/, _memory/, _agents/, _governance/, _connectivity/ each own one concern.
- The README states this is the Community Edition: no operator data, no live projects, and no secrets in-repo.
3. Runtime boot and load order
- The system uses a tiered boot sequence. The root docs and kernel files are loaded first, then deeper context only when needed.
- The documented Tier 0 load path is:
- CLAUDE.md
- CONTEXT.md
- _memory/SESSION-BOOT-STATE.md
- _routing/runtime/ROUTING-KERNEL.md
- _routing/runtime/ROUTE-INDEX.md
- _memory/runtime/MEMORY-KERNEL.md
- _memory/runtime/LOAD-INDEX.md
- This makes the architecture a lazy-load command center, not a monolithic context dump.
4. Routing subsystem
- _routing/ is the decision engine for classifying requests before loading project files.
- Key artifacts:
- _routing/runtime/ROUTING-KERNEL.md and ROUTE-INDEX.md define the live routing model.
- _routing/runtime/routes/*.md contains route cards such as operator-onboarding, project-scaffold, live-system, handoff, memory-write, proof-claims, and role-engagement.
- _routing/new_project_intake.py, _routing/run_gates.py, and gate scripts support deterministic selection and validation.
- Architecturally, requests flow through smallest-match route cards first, then expand to the needed domain files.
5. Memory subsystem
- _memory/ is the long-lived context and recovery layer.
- Important boundaries:
- MEMORY-KERNEL.md defines memory behavior.
- LOAD-INDEX.md controls what memory is loaded.
- SESSION-BOOT-STATE.md captures session startup state.
- decision-log.md, sync-rules.md, memory-rules.md, and runtime logs support exact record and pruning discipline.
- The memory design is explicitly about relevance, exact record, and findability, not just chat history.
6. Agent crew architecture
- _agents/ contains the role-based crew, each with a standard package:
- CONTRACT.md
- doctrine/*
- stages/01_intake through 04_handoff
- Roles include functional boundaries such as analyst, builder, conductor, keeper, liaison, librarian, marshal, mechanic, pathfinder, recorder, scout, sentinel, signal, steward, theorist, voice, and warden.
- This is a multi-agent architecture with role contracts, not a generic prompt collection. Each role has a separate responsibility and handoff spine.
7. Governance, truth, and refusal
- _governance/ and several agent doctrines enforce authority boundaries around claims and decisions.
- Notable governance roles:
- Steward for truth/proof/refusal
- Sentinel for risk gates
- Warden for hard stops on live-system, credentials, money, and deploy actions
- The architecture intentionally blocks unsupported claims, unsafe moves, and irreversible actions until the proper gate or proof condition is met.
8. Live-system and connectivity boundary
- _connectivity/ isolates anything involving environment restoration, vault mapping, tool permissions, or live-system risk.
- Files like env-vault-map.md, live-system-risk-rules.md, tool-permissions.md, and the PowerShell restore scripts define the boundary between local repo work and external/private infrastructure.
- The repo’s rule is that secrets live outside the repo, in a private vault repo, with plaintext .env files ignored locally.
9. Project/venture harness
- _examples/sample-project/ shows how a real venture is structured once scaffolded.
- The intended pattern is that each project gets its own staged folder layout plus local memory/state, while inheriting the root operating rules.
- This means the framework is designed to generate portable project workspaces, not just manage this repository itself.
10. Onboarding and operator entrypoints
- install.py provides a non-agent onboarding path.
- The docs also support an agent-led onboarding flow, starting from GUIDE.md, DISTRIBUTION-README.md, and the runtime route for operator onboarding.
- hello.ps1 and start-atx.bat are convenience launchers for local Windows use.
11. Automation and enforcement
- The repo uses GitHub Actions in .github/workflows/ for gating and distribution checks.
- .githooks/pre-commit and _routing/ci/run-gates.* indicate local and CI-side validation are meant to match.
- The architecture favors deterministic gates: self-tests, role registry checks, and distribution scrub rules before changes move forward.
12. Handoffs, logs, and traceability
- _handoffs/ and _output/ manage structured transfer between phases and outcomes.
- _agents/*/stages/*/CONTRACT.md plus _handoffs/HANDOFF-LOG.md show that work is meant to be auditable across intake, judgment, output, and handoff.
- This creates a traceable workflow where decisions and outputs are first-class artifacts.
13. How data flows through the system
- A request typically enters through the root instructions, is classified by routing, may trigger a risk or live-system gate, then loads the smallest necessary memory and agent doctrine.
- If work is project-specific, the scaffolded venture structure receives the output, and handoff/log artifacts capture the transition.
- The system is therefore a policy-driven orchestration layer: request → route → load → judge/gate → act → handoff.
14. Technology and tooling that materially shape the architecture
- The repo is document-centric, but it also relies on:
- Python for installer/gate scripts
- JavaScript for generators
- PowerShell/Bash for CI and restore scripts
- GitHub Actions for automation
- These tools matter because they implement the routing, gating, and bootstrap behavior that the architecture depends on.
15. Best mental model for a diagram
- Draw this as a center-led OS with four major rings: root identity/governance, routing + memory kernels, agent roles, and project/runtime workspaces.
- Surround that with connectivity/live-system controls and CI/hooks as safety boundaries.
- The key design principle is: minimal context first, strict gates before action, and portable project scaffolds under a stable root policy.
Main entry points: ROUTING-KERNEL.md Routing kernel · _agents Agent crew · _governance Governance · _connectivity Connectivity
Components 19
Root policy
Canonical repo identity, entry docs, and top-level operating rules.
- CLAUDE.md · Canonical root identity and primary system law.
CLAUDE.md - AGENTS.md · Codex-facing loader and repository entrypoint.
AGENTS.md - CONTEXT.md · Shared root context loaded early in the boot sequence.
CONTEXT.md
Routing and memory
Request classification, lazy loading, and durable context control.
- Routing kernel · Live routing model that classifies requests before deeper loads.
_routing/runtime/ROUTING-KERNEL.md - Route index · Index of route cards and route selection surface.
_routing/runtime/ROUTE-INDEX.md - Route cards · Smallest-match route definitions such as onboarding, scaffold, live-system, handoff, and proof claims.
_routing/runtime/routes - Memory kernel · Rules for long-lived context, relevance, and recovery.
_memory/runtime/MEMORY-KERNEL.md - Load index · Controls what memory is loaded and when.
_memory/runtime/LOAD-INDEX.md - Boot state · Captured session startup state and initial recovery anchor.
_memory/SESSION-BOOT-STATE.md
Agent crew
Role-based agents with shared contracts, doctrines, and stage spines.
- Agent crew · Role-based multi-agent system with contracts and handoff stages.
_agents
Safety and live system
Governance, live-system boundaries, credentials, and permission controls.
- Governance · Authority boundaries for proof, refusal, and decision discipline.
_governance - Steward doctrine · Truth, proof, and refusal rules for claims and decisions.
_governance/steward.md - Sentinel doctrine · Risk gating and validation rules for unsafe or uncertain actions.
_agents/sentinel/doctrine/risk-gates.md - Warden doctrine · Hard stops for live-system, credentials, money, and deploy actions.
_agents/warden/doctrine/live-system-hard-stops.md - Connectivity · Environment restore, vault mapping, and tool permission controls.
_connectivity
Project workspaces
Scaffolded project and venture layouts that inherit the root framework.
- Project harness · Portable project/venture workspace pattern inherited from the root.
_examples/sample-project - Handoffs · Structured phase-to-phase transfer and audit trail.
_handoffs - Output area · Repository area for produced outputs and output indexing.
_output
Automation
Bootstrap, hooks, and CI gates that enforce deterministic behavior.
- Bootstrap and CI · Installers, hooks, and workflow gates that enforce deterministic behavior.
Connections 24
- AGENTS.md → CLAUDE.md: loads · Agent-facing entry reads the canonical root identity.
- CLAUDE.md → CONTEXT.md: boot sequence · Root identity leads into shared context.
- CONTEXT.md → Boot state: then loads · Boot context advances into the session state.
- Boot state → Routing kernel: routes to · Startup state feeds the live router.
- Routing kernel → Route index: consults · Router uses the route index to choose a card.
- Route index → Route cards: expands · Route index resolves into specific route cards.
- Routing kernel → Memory kernel: may load · Routing decisions trigger the memory kernel when needed.
- Memory kernel → Load index: controls · Memory kernel delegates load selection to the load index.
- Load index → Route cards: supports · Route cards and memory loading work together for minimal context.
- Routing kernel → Agent crew: dispatches · Classified requests are handed to the appropriate role.
- Agent crew → Steward doctrine: checks truth · Agents rely on steward rules for proof and refusal.
- Agent crew → Sentinel doctrine: checks risk · Agents pass through risk gates before sensitive actions.
- Agent crew → Warden doctrine: obeys stops · Agents respect hard-stop rules for live-system actions.
- Governance → Steward doctrine: contains · Governance centralizes truth and proof rules.
- Governance → Sentinel doctrine: contains · Governance centralizes risk gates.
- Governance → Warden doctrine: contains · Governance centralizes hard-stop policy.
- Connectivity → Warden doctrine: bounded by · Live-system and credential access is constrained by hard stops.
- Connectivity → Bootstrap and CI: enforced by · Restore scripts and permissions feed the automation boundary.
- Project harness → Handoffs: records · Project workspaces emit structured handoffs.
- Project harness → Output area: produces · Scaffolded work lands in the output area.
- Bootstrap and CI → Routing kernel: validates · CI and hooks run routing and gate checks.
- Bootstrap and CI → Agent crew: checks · Automation verifies crew contracts and stage rules.
- Bootstrap and CI → Connectivity: scrubs · Distribution and environment checks protect the live boundary.
- Route cards → Project harness: creates · Project-scaffold routes lead into portable workspaces.