# jordansshaw-pixel/command-center-os-starter architecture

> Architecture diagram of the GitHub repository jordansshaw-pixel/command-center-os-starter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jordansshaw-pixel/command-center-os-starter
- Repository: https://github.com/jordansshaw-pixel/command-center-os-starter

## Overview

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/runtime/ROUTING-KERNEL.md`](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_routing/runtime/ROUTING-KERNEL.md) (Routing kernel), [`_agents`](https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_agents) (Agent crew), [`_governance`](https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_governance) (Governance), [`_connectivity`](https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_connectivity) (Connectivity)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_root["Root policy"]
  node_claude_md["CLAUDE.md<br/>root identity<br/>[CLAUDE.md]"]
  node_agents_md["AGENTS.md<br/>agent entry<br/>[AGENTS.md]"]
  node_context_md["CONTEXT.md<br/>boot context<br/>[CONTEXT.md]"]
end

subgraph group_grp_routing["Routing and memory"]
  node_routing_kernel["Routing kernel<br/>router core<br/>[ROUTING-KERNEL.md]"]
  node_route_index["Route index<br/>route catalog<br/>[ROUTE-INDEX.md]"]
  node_routing_runtime_routes["Route cards<br/>route set"]
  node_memory_kernel["Memory kernel<br/>memory core<br/>[MEMORY-KERNEL.md]"]
  node_load_index["Load index<br/>memory index<br/>[LOAD-INDEX.md]"]
  node_session_boot_state["Boot state<br/>session state"]
end

subgraph group_grp_agents["Agent crew"]
  node_agent_crew["Agent crew<br/>role system"]
end

subgraph group_grp_safety["Safety and live system"]
  node_governance["Governance<br/>truth and gate"]
  node_steward_doctrine["Steward doctrine<br/>truth gate<br/>[steward.md]"]
  node_sentinel_doctrine["Sentinel doctrine<br/>risk gate<br/>[risk-gates.md]"]
  node_warden_doctrine["Warden doctrine<br/>hard stop"]
  node_connectivity["Connectivity<br/>live-system boundary"]
end

subgraph group_grp_workspaces["Project workspaces"]
  node_project_harness["Project harness<br/>scaffold template"]
  node_handoffs["Handoffs<br/>transfer log"]
  node_output_area["Output area<br/>result store"]
end

subgraph group_grp_automation["Automation"]
  node_bootstrap_ci["Bootstrap and CI<br/>automation"]
end

node_agents_md -->|"loads"| node_claude_md
node_claude_md -->|"boot sequence"| node_context_md
node_context_md -->|"then loads"| node_session_boot_state
node_session_boot_state -->|"routes to"| node_routing_kernel
node_routing_kernel -->|"consults"| node_route_index
node_route_index -->|"expands"| node_routing_runtime_routes
node_routing_kernel -->|"may load"| node_memory_kernel
node_memory_kernel -->|"controls"| node_load_index
node_load_index -->|"supports"| node_routing_runtime_routes
node_routing_kernel -->|"dispatches"| node_agent_crew
node_agent_crew -->|"checks truth"| node_steward_doctrine
node_agent_crew -->|"checks risk"| node_sentinel_doctrine
node_agent_crew -->|"obeys stops"| node_warden_doctrine
node_governance -->|"contains"| node_steward_doctrine
node_governance -->|"contains"| node_sentinel_doctrine
node_governance -->|"contains"| node_warden_doctrine
node_connectivity -->|"bounded by"| node_warden_doctrine
node_connectivity -->|"enforced by"| node_bootstrap_ci
node_project_harness -->|"records"| node_handoffs
node_project_harness -->|"produces"| node_output_area
node_bootstrap_ci -->|"validates"| node_routing_kernel
node_bootstrap_ci -->|"checks"| node_agent_crew
node_bootstrap_ci -->|"scrubs"| node_connectivity
node_routing_runtime_routes -->|"creates"| node_project_harness

click node_claude_md "https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/CLAUDE.md"
click node_agents_md "https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/AGENTS.md"
click node_context_md "https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/CONTEXT.md"
click node_routing_kernel "https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_routing/runtime/ROUTING-KERNEL.md"
click node_route_index "https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_routing/runtime/ROUTE-INDEX.md"
click node_routing_runtime_routes "https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_routing/runtime/routes"
click node_memory_kernel "https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_memory/runtime/MEMORY-KERNEL.md"
click node_load_index "https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_memory/runtime/LOAD-INDEX.md"
click node_session_boot_state "https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_memory/SESSION-BOOT-STATE.md"
click node_agent_crew "https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_agents"
click node_governance "https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_governance"
click node_steward_doctrine "https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_governance/steward.md"
click node_sentinel_doctrine "https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_agents/sentinel/doctrine/risk-gates.md"
click node_warden_doctrine "https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_agents/warden/doctrine/live-system-hard-stops.md"
click node_connectivity "https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_connectivity"
click node_project_harness "https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_examples/sample-project"
click node_handoffs "https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_handoffs"
click node_output_area "https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_output"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_claude_md,node_agents_md,node_context_md toneBlue
class node_routing_kernel,node_route_index,node_routing_runtime_routes,node_memory_kernel,node_load_index,node_session_boot_state toneAmber
class node_agent_crew toneMint
class node_governance,node_steward_doctrine,node_sentinel_doctrine,node_warden_doctrine,node_connectivity toneRose
class node_project_harness,node_handoffs,node_output_area toneIndigo
class node_bootstrap_ci toneTeal
```

## Components

### Root policy

Canonical repo identity, entry docs, and top-level operating rules.

- [CLAUDE.md](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/CLAUDE.md): root identity · Canonical root identity and primary system law. · `CLAUDE.md`
- [AGENTS.md](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/AGENTS.md): agent entry · Codex-facing loader and repository entrypoint. · `AGENTS.md`
- [CONTEXT.md](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/CONTEXT.md): boot context · Shared root context loaded early in the boot sequence. · `CONTEXT.md`

### Routing and memory

Request classification, lazy loading, and durable context control.

- [Routing kernel](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_routing/runtime/ROUTING-KERNEL.md): router core · Live routing model that classifies requests before deeper loads. · `_routing/runtime/ROUTING-KERNEL.md`
- [Route index](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_routing/runtime/ROUTE-INDEX.md): route catalog · Index of route cards and route selection surface. · `_routing/runtime/ROUTE-INDEX.md`
- [Route cards](https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_routing/runtime/routes): route set · Smallest-match route definitions such as onboarding, scaffold, live-system, handoff, and proof claims. · `_routing/runtime/routes`
- [Memory kernel](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_memory/runtime/MEMORY-KERNEL.md): memory core · Rules for long-lived context, relevance, and recovery. · `_memory/runtime/MEMORY-KERNEL.md`
- [Load index](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_memory/runtime/LOAD-INDEX.md): memory index · Controls what memory is loaded and when. · `_memory/runtime/LOAD-INDEX.md`
- [Boot state](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_memory/SESSION-BOOT-STATE.md): session 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](https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_agents): role system · Role-based multi-agent system with contracts and handoff stages. · `_agents`

### Safety and live system

Governance, live-system boundaries, credentials, and permission controls.

- [Governance](https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_governance): truth and gate · Authority boundaries for proof, refusal, and decision discipline. · `_governance`
- [Steward doctrine](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_governance/steward.md): truth gate · Truth, proof, and refusal rules for claims and decisions. · `_governance/steward.md`
- [Sentinel doctrine](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_agents/sentinel/doctrine/risk-gates.md): risk gate · Risk gating and validation rules for unsafe or uncertain actions. · `_agents/sentinel/doctrine/risk-gates.md`
- [Warden doctrine](https://github.com/jordansshaw-pixel/command-center-os-starter/blob/main/_agents/warden/doctrine/live-system-hard-stops.md): hard stop · Hard stops for live-system, credentials, money, and deploy actions. · `_agents/warden/doctrine/live-system-hard-stops.md`
- [Connectivity](https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_connectivity): live-system boundary · Environment restore, vault mapping, and tool permission controls. · `_connectivity`

### Project workspaces

Scaffolded project and venture layouts that inherit the root framework.

- [Project harness](https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_examples/sample-project): scaffold template · Portable project/venture workspace pattern inherited from the root. · `_examples/sample-project`
- [Handoffs](https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_handoffs): transfer log · Structured phase-to-phase transfer and audit trail. · `_handoffs`
- [Output area](https://github.com/jordansshaw-pixel/command-center-os-starter/tree/main/_output): result store · Repository area for produced outputs and output indexing. · `_output`

### Automation

Bootstrap, hooks, and CI gates that enforce deterministic behavior.

- **Bootstrap and CI**: automation · Installers, hooks, and workflow gates that enforce deterministic behavior.

## Connections

- 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.