# kmosoti/blackcell architecture

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

- Interactive diagram: https://gitdiagram.com/kmosoti/blackcell
- Repository: https://github.com/kmosoti/blackcell

## Overview

1. **Overall shape**
   BlackCell is a Python CLI/application that models a repository, derives typed facts from it, reasons with symbolic constraints, and then plans or runs agent work through interchangeable runtimes. The architecture is intentionally modular: observation, reasoning, planning, runtime execution, and trace capture are separated into distinct packages.

2. **Primary entry points**
   The user-facing entry point is the `blackcell` CLI in `src/blackcell/cli/app.py`, with output formatting in `src/blackcell/cli/output.py`. The README’s commands (`world observe`, `nesy validate`, `harness plan`, `harness run`) map to these subsystems, so the CLI is the top-level orchestration layer.

3. **Configuration and environment**
   Repository behavior is driven by configuration loaders in `src/blackcell/config`, backed by `blackcell.toml`, `blackcell.plan.yaml`, and environment handling in `src/blackcell/config/env.py`. This is the boundary where repo-specific settings, runtime selection, and workflow parameters are normalized before entering the rest of the system.

4. **World-model subsystem**
   `src/blackcell/world` is the repository-understanding layer. Its job is to hold the typed representation of the repo’s current state, likely derived from files, docs, and other observed signals. In the README’s framing, this is where “evidence” becomes a compact internal model.

5. **NeSy reasoning subsystem**
   `src/blackcell/nesy` implements the lightweight symbolic reasoning layer. It sits on top of the world model and works with typed facts and rules rather than a heavy ML stack. This is the layer that turns observed state into beliefs, constraints, or validations that can influence planning.

6. **Planning and execution harness**
   `src/blackcell/harness` is the runtime-agnostic execution boundary. It appears to own the planning and run lifecycle: producing an execution plan, then dispatching work into whichever runtime adapter is selected. This is the main “do work” boundary between internal reasoning and external execution.

7. **Runtime adapters**
   `src/blackcell/runtime` abstracts how work is actually executed, and `src/blackcell/runtime/service.py` suggests a service layer around adapter selection and invocation. The README’s emphasis on interchangeable runtimes means this package is a key architectural seam: the planning layer stays stable while execution backends can vary.

8. **Agent model and registry**
   `src/blackcell/agents` defines the agent-facing abstractions and metadata. `models.py`, `registry.py`, and `opencode.py` indicate support for multiple agent definitions and integration with specific agent ecosystems. This package is where agent capabilities are described and resolved before being rendered into workflows.

9. **Control plane**
   `src/blackcell/control_plane` is the highest-level orchestration domain beyond the CLI. It includes loading, validation, schema/model definitions, rendering, sync, Git integration, project fields, capability handling, PR support, and codex CLI integration. This package is likely responsible for turning repository state plus configuration into actionable agent workflows and synchronizing those workflows with external systems.

10. **External integrations**
   The main external boundary is GitHub, exposed through `src/blackcell/providers/github.py` and its registry. The generated cache `generated/cache/github_graphql_capabilities.json` and the script `scripts/github_graphql_capabilities.py` indicate a data-refresh path for API capability discovery. This is important for architecture because part of the system depends on external GitHub metadata rather than only local repo files.

11. **Traceability and state change tracking**
   The README emphasizes explicit traces, surprises, and revisions; those concerns are reflected across `world`, `harness`, `vanguard`, and `control_plane`. `src/blackcell/vanguard` appears to model change specifications and state transitions, which likely serve as the repository’s audit/change tracking layer feeding back into the world model and planning decisions.

12. **Documentation and research as first-class artifacts**
   The `docs/` tree is unusually rich and functionally important: it defines the conceptual model (`world-model`, `nesy`, `harness`, `runtime-adapters`), architectural decisions, glossary, and target environments (`codex-cli`, `containers`, `opencode`). This suggests the repo’s architecture is partly encoded as living documentation, not just code.

13. **Test structure**
   `tests/unit` mirrors the major packages and validates them in isolation: agents, config, control plane, harness, runtime adapters, world model, NeSy, Vanguard, GitHub provider, and CLI behavior. That test layout reinforces the boundaries of the system and indicates the intended dependency direction: lower-level models/services are tested separately from CLI wiring.

14. **Deployment and development environment**
   The repository is container-aware (`Containerfile`, `compose.yaml`, `.devcontainer/`) and pinned to a Python toolchain (`pyproject.toml`, `uv.lock`, `.python-version`). This matters architecturally because the project is designed to run consistently in local CLI, devcontainer, and containerized contexts, which aligns with the runtime-agnostic harness goal.

15. **Data flow in one line**
   The core flow is: repository and configuration are observed, observations are converted into typed world facts, NeSy rules refine those facts into beliefs/constraints, the harness turns those into plans, runtime adapters execute the plan, and traces feed back into the world/control-plane layers for revision and synchronization.

Main entry points: [`src/blackcell/cli/app.py`](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/cli/app.py) (CLI app), [`src/blackcell/control_plane/facade.py`](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/facade.py) (Control facade), [`src/blackcell/harness/service.py`](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/harness/service.py) (Harness), [`src/blackcell/world/service.py`](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/world/service.py) (World service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_cli["CLI & config"]
  node_cli_app["CLI app<br/>entrypoint<br/>[app.py]"]
  node_cli_output["Output<br/>formatting<br/>[output.py]"]
  node_config_loader["Config loader<br/>[loader.py]"]
  node_config_models["Config models<br/>config schema<br/>[models.py]"]
  node_config_env["Env<br/>[env.py]"]
end

subgraph group_group_core["Core model"]
  node_world_service[("World service<br/>repo model<br/>[service.py]")]
  node_world_models["World facts<br/>state model<br/>[models.py]"]
  node_nesy_service{{"NeSy service<br/>symbolic reasoning<br/>[service.py]"}}
  node_nesy_models["NeSy model<br/>rules/facts<br/>[models.py]"]
  node_vanguard_changes["Change spec<br/>state change<br/>[changespec.py]"]
end

subgraph group_group_execution["Planning & execution"]
  node_harness_service{{"Harness<br/>planner<br/>[service.py]"}}
  node_harness_models["Plan model<br/>plan schema<br/>[models.py]"]
  node_runtime_service["Runtime service<br/>adapter dispatch<br/>[service.py]"]
  node_runtime_models["Runtime model<br/>runtime schema<br/>[models.py]"]
  node_agents_registry["Agent registry<br/>agent catalog<br/>[registry.py]"]
  node_agents_models["Agent models<br/>agent schema<br/>[models.py]"]
end

subgraph group_group_control["Control plane"]
  node_control_facade{{"Control facade<br/>orchestration<br/>[facade.py]"}}
  node_control_workflow["Workflow<br/>[agent_workflow.py]"]
  node_control_rendering["Rendering<br/>templating<br/>[rendering.py]"]
  node_control_validation["Validation<br/>schema checks<br/>[validation.py]"]
  node_control_sync["Sync<br/>[sync.py]"]
  node_control_capabilities["Capabilities<br/>feature discovery<br/>[capabilities.py]"]
end

subgraph group_group_integrations["Integrations"]
  node_github_provider["GitHub provider<br/>external provider<br/>[github.py]"]
  node_github_caps_cache["Caps cache<br/>generated data"]
end

node_cli_app -->|"loads"| node_config_loader
node_cli_app -->|"observes"| node_world_service
node_cli_app -->|"validates"| node_nesy_service
node_cli_app -->|"plans/runs"| node_harness_service
node_cli_app -->|"orchestrates"| node_control_facade
node_cli_app -->|"formats"| node_cli_output
node_config_loader -->|"produces"| node_config_models
node_config_loader -->|"reads"| node_config_env
node_world_service -->|"stores"| node_world_models
node_world_service -->|"tracks"| node_vanguard_changes
node_world_service -->|"feeds"| node_nesy_service
node_nesy_service -->|"uses"| node_nesy_models
node_nesy_service -->|"influences"| node_harness_service
node_harness_service -->|"builds"| node_harness_models
node_harness_service -->|"dispatches"| node_runtime_service
node_runtime_service -->|"implements"| node_runtime_models
node_agents_registry -->|"resolves"| node_agents_models
node_control_facade -->|"assembles"| node_control_workflow
node_control_facade -->|"renders"| node_control_rendering
node_control_facade -->|"checks"| node_control_validation
node_control_facade -->|"syncs"| node_control_sync
node_control_workflow -->|"selects"| node_agents_registry
node_control_workflow -->|"plans"| node_harness_service
node_control_rendering -->|"formats"| node_agents_models
node_control_validation -->|"applies"| node_config_models
node_control_sync -->|"uses"| node_github_provider
node_control_capabilities -->|"discovers"| node_github_provider
node_control_capabilities -->|"reads"| node_github_caps_cache

click node_cli_app "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/cli/app.py"
click node_cli_output "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/cli/output.py"
click node_config_loader "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/config/loader.py"
click node_config_models "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/config/models.py"
click node_config_env "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/config/env.py"
click node_world_service "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/world/service.py"
click node_world_models "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/world/models.py"
click node_nesy_service "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/nesy/service.py"
click node_nesy_models "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/nesy/models.py"
click node_vanguard_changes "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/vanguard/changespec.py"
click node_harness_service "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/harness/service.py"
click node_harness_models "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/harness/models.py"
click node_runtime_service "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/runtime/service.py"
click node_runtime_models "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/runtime/models.py"
click node_agents_registry "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/agents/registry.py"
click node_agents_models "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/agents/models.py"
click node_control_facade "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/facade.py"
click node_control_workflow "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/agent_workflow.py"
click node_control_rendering "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/rendering.py"
click node_control_validation "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/validation.py"
click node_control_sync "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/sync.py"
click node_control_capabilities "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/capabilities.py"
click node_github_provider "https://github.com/kmosoti/blackcell/blob/main/src/blackcell/providers/github.py"
click node_github_caps_cache "https://github.com/kmosoti/blackcell/blob/main/generated/cache/github_graphql_capabilities.json"

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_cli_app,node_cli_output,node_config_loader,node_config_models,node_config_env toneBlue
class node_world_service,node_world_models,node_nesy_service,node_nesy_models,node_vanguard_changes toneAmber
class node_harness_service,node_harness_models,node_runtime_service,node_runtime_models,node_agents_registry,node_agents_models toneMint
class node_control_facade,node_control_workflow,node_control_rendering,node_control_validation,node_control_sync,node_control_capabilities toneRose
class node_github_provider,node_github_caps_cache toneIndigo
```

## Components

### CLI & config

User entrypoints and repository/runtime configuration.

- [CLI app](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/cli/app.py): entrypoint · Top-level blackcell command and subcommand orchestration. · `src/blackcell/cli/app.py`
- [Output](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/cli/output.py): formatting · Human-readable and structured CLI output helpers. · `src/blackcell/cli/output.py`
- [Config loader](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/config/loader.py): config · Loads repository settings and normalizes workflow/runtime configuration. · `src/blackcell/config/loader.py`
- [Config models](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/config/models.py): config schema · Typed configuration and environment models. · `src/blackcell/config/models.py`
- [Env](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/config/env.py): env binding · Environment-variable and process-context handling. · `src/blackcell/config/env.py`

### Core model

Repository state, symbolic reasoning, and change tracking.

- [World service](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/world/service.py): repo model · Builds and updates the typed repository world model from observations. · `src/blackcell/world/service.py`
- [World facts](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/world/models.py): state model · Typed facts and repository-state structures. · `src/blackcell/world/models.py`
- [NeSy service](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/nesy/service.py): symbolic reasoning · Applies rules and constraints over the world model. · `src/blackcell/nesy/service.py`
- [NeSy model](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/nesy/models.py): rules/facts · Symbolic reasoning inputs and outputs. · `src/blackcell/nesy/models.py`
- [Change spec](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/vanguard/changespec.py): state change · Describes revisions, surprises, and tracked state transitions. · `src/blackcell/vanguard/changespec.py`

### Planning & execution

Planning, runtime dispatch, and agent abstraction.

- [Harness](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/harness/service.py): planner · Creates plans and coordinates execution lifecycle. · `src/blackcell/harness/service.py`
- [Plan model](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/harness/models.py): plan schema · Execution-plan and harness data structures. · `src/blackcell/harness/models.py`
- [Runtime service](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/runtime/service.py): adapter dispatch · Selects and invokes interchangeable runtime backends. · `src/blackcell/runtime/service.py`
- [Runtime model](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/runtime/models.py): runtime schema · Runtime adapter interfaces and execution records. · `src/blackcell/runtime/models.py`
- [Agent registry](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/agents/registry.py): agent catalog · Resolves agent definitions and capabilities. · `src/blackcell/agents/registry.py`
- [Agent models](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/agents/models.py): agent schema · Agent metadata and capability structures. · `src/blackcell/agents/models.py`

### Control plane

Workflow assembly, rendering, validation, sync, and external capability handling.

- [Control facade](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/facade.py): orchestration · High-level control plane entry that stitches workflow pieces together. · `src/blackcell/control_plane/facade.py`
- [Workflow](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/agent_workflow.py): workflow assembly · Builds agent workflows from repo state and configuration. · `src/blackcell/control_plane/agent_workflow.py`
- [Rendering](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/rendering.py): templating · Renders agents, workflows, and control-plane artifacts. · `src/blackcell/control_plane/rendering.py`
- [Validation](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/validation.py): schema checks · Validates control-plane inputs and generated artifacts. · `src/blackcell/control_plane/validation.py`
- [Sync](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/sync.py): repository sync · Synchronizes generated control-plane state back to the repository and Git context. · `src/blackcell/control_plane/sync.py`
- [Capabilities](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/control_plane/capabilities.py): feature discovery · Tracks supported capabilities and external feature discovery. · `src/blackcell/control_plane/capabilities.py`

### Integrations

External provider and generated capability data.

- [GitHub provider](https://github.com/kmosoti/blackcell/blob/main/src/blackcell/providers/github.py): external provider · GitHub-backed provider implementation and API boundary. · `src/blackcell/providers/github.py`
- [Caps cache](https://github.com/kmosoti/blackcell/blob/main/generated/cache/github_graphql_capabilities.json): generated data · Cached GitHub GraphQL capability data used by control-plane discovery. · `generated/cache/github_graphql_capabilities.json`

## Connections

- CLI app → Config loader: loads · CLI boots from repository and runtime configuration.
- CLI app → World service: observes · User commands can derive the repository world model.
- CLI app → NeSy service: validates · CLI exposes symbolic validation flows.
- CLI app → Harness: plans/runs · CLI drives planning and execution workflows.
- CLI app → Control facade: orchestrates · CLI can enter the control-plane workflow stack.
- CLI app → Output: formats · Output rendering is separated from command logic.
- Config loader → Config models: produces · Parsed configuration is normalized into typed models.
- Config loader → Env: reads · Configuration is influenced by environment context.
- World service → World facts: stores · World service populates the repository state model.
- World service → Change spec: tracks · State changes and surprises feed revision tracking.
- World service → NeSy service: feeds · World facts are the input to symbolic reasoning.
- NeSy service → NeSy model: uses · Reasoning operates over typed facts and constraints.
- NeSy service → Harness: influences · Reasoning output shapes the plan and execution decisions.
- Harness → Plan model: builds · Harness creates execution plans and lifecycle state.
- Harness → Runtime service: dispatches · Planned work is handed to a selected runtime backend.
- Runtime service → Runtime model: implements · Runtime service conforms to adapter contracts.
- Agent registry → Agent models: resolves · Agent registry is backed by typed agent definitions.
- Control facade → Workflow: assembles · Facade coordinates workflow construction.
- Control facade → Rendering: renders · Facade produces control-plane artifacts.
- Control facade → Validation: checks · Facade validates generated state and inputs.
- Control facade → Sync: syncs · Facade coordinates synchronization of generated artifacts.
- Workflow → Agent registry: selects · Workflows resolve agent implementations through the registry.
- Workflow → Harness: plans · Workflow output is executed through the harness.
- Rendering → Agent models: formats · Rendering turns agent metadata into executable artifacts.
- Validation → Config models: applies · Validation enforces repository and workflow configuration.
- Sync → GitHub provider: uses · Sync integrates with GitHub-backed repository services.
- Capabilities → GitHub provider: discovers · Capabilities are derived from provider support.
- Capabilities → Caps cache: reads · Capability discovery uses generated cached metadata.
