# asi-rishi/boros-architecture architecture

> Architecture diagram of the GitHub repository asi-rishi/boros-architecture, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/asi-rishi/boros-architecture
- Repository: https://github.com/asi-rishi/boros-architecture

## Overview

1. **What this repository is**
   Boros is an autonomous agent substrate, not a conventional app. The runtime repeatedly alternates between a self-improvement loop and a task-execution loop. The codebase is organized so the system can inspect itself, mutate its own skills, evaluate those mutations, and roll them back if they regress.

2. **The bootstrap/runtime core**
   `boros/kernel.py` is the entrypoint and thin bootstrap layer. It reads the manifest, loads the boot skills in order, wires tool dispatch, and keeps the runtime small so most behavior lives in skills rather than the kernel.

3. **Model/provider boundary**
   `boros/adapters/providers/` contains LLM-provider adapters for Anthropic, OpenAI, Gemini, Ollama, and OpenAI-compatible endpoints. This is the model boundary: the kernel and skills call through adapters rather than hard-coding one model family. The readme indicates Claude is the primary substrate and GPT-4o is used for meta-evaluation / eval generation.

4. **Configuration and system contract**
   `boros/manifest.json`, `boros/config.json`, `.env`, and `boros/world_model.json` define the operating contract. The manifest drives mode, boot order, and model selection; `config.json` controls runtime limits and logging; `.env` supplies API keys; `world_model.json` defines the scoring categories that steer evolution and is treated as read-only by Boros.

5. **Skill-based architecture**
   The real system behavior lives under `boros/skills/`. Each skill is a self-contained module with:
   - `SKILL.md` describing its contract,
   - `functions/` implementing callable tools,
   - `skill.json` metadata,
   - optional `state/`, `metrics/`, and `changelog.md`.
   This makes the system modular and evolvable at the capability level rather than as a monolith.

6. **Boot skills vs demand skills**
   The boot set establishes identity, mode, time, memory, routing, context loading, reflection, meta-evolution, meta-evaluation, and loop orchestration. Demand skills are invoked as needed for work: skill forge, mission control, reasoning, tool use, communication, web research, eval bridge, and scratchpad. That split is an important boundary: boot skills make the agent self-sustaining; demand skills provide operational capabilities.

7. **Primary control loops**
   `boros/skills/loop-orchestrator/` manages the lifecycle state machine, including starting cycles, advancing stages, ending cycles, and storing `loop_state.json`. The system runs in `evolution`, `work`, or `dual` mode, with cycle progression controlled by persisted loop state rather than ephemeral process memory.

8. **Self-improvement pipeline**
   The evolutionary loop is REFLECT → EVOLVE → EVAL. Reflection draws on memory and logs to form a hypothesis; meta-evolution proposes and applies code changes; meta-evaluation reviews the patch with an external model; eval-bridge then connects to the independent eval generator. This pipeline is the core data flow for improving Boros itself.

9. **Memory and context management**
   `boros/skills/memory/` and `boros/skills/context-orchestration/` implement the tiered memory system. Memory handles page-in/page-out, archival commits, and search; context orchestration decides what the model should see at a given moment. Persistent artifacts under `boros/memory/`, `boros/session/`, and `boros/logs/` feed these skills, enabling long-running continuity without loading everything into context.

10. **Evaluation subsystem**
   `boros/eval-generator/` is a separate evaluation pipeline with its own config, shared request/result folders, and tool dispatcher. It executes isolated tasks, records outcomes, and feeds scores back through the eval bridge skills under `boros/skills/eval-bridge/`. This is a critical architectural boundary: Boros is tested by an external process that it does not directly control.

11. **Self-modification and rollback**
   `boros/skills/skill-forge/` is the code mutation boundary. It can snapshot code, apply diffs, validate changes, run test suites, invoke tooling, and roll back. The repository also contains `boros/snapshots/` for saved states and rollback support. This is how the system edits its own implementation while preserving recovery paths.

12. **Work execution and human-facing control**
   `boros/skills/mission-control/`, `boros/skills/tool-use/`, and `boros/skills/director-interface/` handle task intake, terminal/file operations, and Director commands. The readme’s CLI commands map to these subsystems: status, pause/resume, inject, forge, set-mode, task, eval, approve/flag, rollback. This is the operational interface separating direct human intent from autonomous execution.

13. **Specialized capability islands**
   Additional skills such as reasoning, reflection, communication, web research, scratchpad, identity, mode control, and temporal consciousness are narrow subsystems with explicit tool surfaces. They each persist their own metrics and state, which makes the architecture compositional: capability improvements can happen inside one island without rewriting the whole system.

14. **Repository shape and non-runtime assets**
   `predev-specs/` holds design/specification artifacts and historical decisions, not live runtime logic. `commands/`, `session/`, `memory/`, `logs/`, `metrics/`, and `state/` directories are the persistent operational layer that records system history, scores, and control state. Together they form the traceability backbone for the agent’s continuous self-evolution.

Main entry points: [`Boros/boros/skills/skill-router`](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/skill-router) (Skill router), [`Boros/boros/kernel.py`](https://github.com/asi-rishi/boros-architecture/blob/master/Boros/boros/kernel.py) (Kernel), [`Boros/boros/skills/meta-evolution`](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/meta-evolution) (Meta-evolution), [`Boros/boros/skills/reflection`](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/reflection) (Reflection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Runtime core"]
  node_kernel["Kernel<br/>bootstrap/runtime<br/>[kernel.py]"]
  node_manifest["Manifest<br/>runtime contract<br/>[manifest.json]"]
  node_config["Config<br/>[config.json]"]
  node_providers[("Model adapters<br/>llm boundary")]
  node_router["Skill router<br/>tool registry"]
  node_world["World model<br/>evaluation rubric<br/>[world_model.json]"]
end

subgraph group_boot["Boot skills"]
  node_identity["Identity<br/>boot skill"]
  node_mode["Mode control<br/>boot skill"]
  node_time["Time<br/>boot skill"]
  node_context["Context<br/>boot skill"]
  node_memory["Memory<br/>boot skill"]
  node_loop["Loop orchestrator<br/>state machine"]
end

subgraph group_capabilities["Capability skills"]
  node_mission["Mission control<br/>task intake"]
  node_tooluse["Tool use<br/>execution tools"]
  node_reason["Reasoning<br/>cognition skill"]
  node_comm["Communication<br/>interaction skill"]
  node_research["Web research<br/>research skill"]
  node_scratch["Scratchpad<br/>working memory"]
end

subgraph group_evolution["Self-improvement"]
  node_reflection["Reflection<br/>evolution skill"]
  node_metaevo["Meta-evolution<br/>mutation skill"]
  node_metaeval["Meta-evaluation<br/>review skill"]
  node_evalbridge["Eval bridge<br/>eval connector"]
  node_forge["Skill forge<br/>self-mod tool"]
  node_evalgen[("Eval generator<br/>external pipeline")]
end

subgraph group_storage["Persistent state"]
  node_session["Session state<br/>persistence"]
  node_logs["Logs<br/>trace store"]
  node_memorystore["Memory store<br/>artifact store"]
  node_commands["Commands<br/>control queue"]
  node_snapshots[("Snapshots<br/>rollback store")]
end

subgraph group_specs["Specs"]
  node_predev["Predev specs<br/>design docs"]
end

node_kernel -->|"reads"| node_manifest
node_kernel -->|"loads"| node_config
node_kernel -->|"dispatches"| node_router
node_kernel -->|"calls"| node_providers
node_kernel -->|"boots"| node_identity
node_kernel -->|"boots"| node_mode
node_kernel -->|"boots"| node_time
node_kernel -->|"boots"| node_context
node_kernel -->|"boots"| node_loop
node_router -->|"exposes"| node_memory
node_router -->|"exposes"| node_reflection
node_router -->|"exposes"| node_metaevo
node_router -->|"exposes"| node_metaeval
node_router -->|"exposes"| node_evalbridge
node_router -->|"exposes"| node_forge
node_router -->|"exposes"| node_mission
node_router -->|"exposes"| node_tooluse
node_router -->|"exposes"| node_reason
node_router -->|"exposes"| node_comm
node_router -->|"exposes"| node_research
node_router -->|"exposes"| node_scratch
node_loop -->|"persists"| node_session
node_loop -->|"records"| node_logs
node_reflection -->|"reads"| node_memorystore
node_reflection -->|"analyzes"| node_logs
node_reflection -->|"feeds"| node_metaevo
node_metaevo -->|"uses"| node_forge
node_metaevo -->|"writes"| node_snapshots
node_metaevo -->|"updates"| node_loop
node_metaeval -->|"scores by"| node_world
node_metaeval -->|"routes"| node_evalbridge
node_evalbridge -->|"connects"| node_evalgen
node_evalgen -->|"returns scores"| node_metaeval
node_mission -->|"drives"| node_tooluse
node_mission -->|"reads"| node_commands
node_tooluse -->|"traces"| node_logs
node_context -->|"derives"| node_manifest
node_memory -->|"pages"| node_memorystore
node_memory -->|"uses"| node_session
node_predev -.->|"specifies"| node_router

click node_kernel "https://github.com/asi-rishi/boros-architecture/blob/master/Boros/boros/kernel.py"
click node_manifest "https://github.com/asi-rishi/boros-architecture/blob/master/Boros/boros/manifest.json"
click node_config "https://github.com/asi-rishi/boros-architecture/blob/master/Boros/boros/config.json"
click node_providers "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/adapters/providers"
click node_router "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/skill-router"
click node_identity "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/identity"
click node_mode "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/mode-controller"
click node_time "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/temporal-consciousness"
click node_context "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/context-orchestration"
click node_memory "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/memory"
click node_loop "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/loop-orchestrator"
click node_reflection "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/reflection"
click node_metaevo "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/meta-evolution"
click node_metaeval "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/meta-evaluation"
click node_evalbridge "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/eval-bridge"
click node_forge "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/skill-forge"
click node_mission "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/mission-control"
click node_tooluse "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/tool-use"
click node_reason "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/reasoning"
click node_comm "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/communication"
click node_research "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/web-research"
click node_scratch "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/scratchpad"
click node_evalgen "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/eval-generator"
click node_session "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/session"
click node_logs "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/logs"
click node_memorystore "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/memory"
click node_commands "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/commands"
click node_snapshots "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/snapshots"
click node_predev "https://github.com/asi-rishi/boros-architecture/tree/master/Boros/predev-specs"
click node_world "https://github.com/asi-rishi/boros-architecture/blob/master/Boros/boros/world_model.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_kernel,node_manifest,node_config,node_providers,node_router,node_world toneBlue
class node_identity,node_mode,node_time,node_context,node_memory,node_loop toneAmber
class node_mission,node_tooluse,node_reason,node_comm,node_research,node_scratch toneMint
class node_reflection,node_metaevo,node_metaeval,node_evalbridge,node_forge,node_evalgen toneRose
class node_session,node_logs,node_memorystore,node_commands,node_snapshots toneIndigo
class node_predev toneTeal
```

## Components

### Runtime core

Bootstrap, model boundary, and control wiring.

- [Kernel](https://github.com/asi-rishi/boros-architecture/blob/master/Boros/boros/kernel.py): bootstrap/runtime · Entrypoint that reads the manifest, loads boot skills, and wires dispatch. · `Boros/boros/kernel.py`
- [Manifest](https://github.com/asi-rishi/boros-architecture/blob/master/Boros/boros/manifest.json): runtime contract · Declares mode, boot order, and model selection. · `Boros/boros/manifest.json`
- [Config](https://github.com/asi-rishi/boros-architecture/blob/master/Boros/boros/config.json): runtime config · Controls limits, logging, and runtime behavior. · `Boros/boros/config.json`
- [Model adapters](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/adapters/providers): llm boundary · Provider adapters for Anthropic, OpenAI, Gemini, Ollama, and compatible endpoints. · `Boros/boros/adapters/providers`
- [Skill router](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/skill-router): tool registry · Exposes skill metadata and the active tool set. · `Boros/boros/skills/skill-router`
- [World model](https://github.com/asi-rishi/boros-architecture/blob/master/Boros/boros/world_model.json): evaluation rubric · Read-only scoring categories that steer evolution. · `Boros/boros/world_model.json`

### Boot skills

Skills loaded early to establish state and control.

- [Identity](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/identity): boot skill · Reads and updates agent identity state. · `Boros/boros/skills/identity`
- [Mode control](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/mode-controller): boot skill · Gets and sets operating mode. · `Boros/boros/skills/mode-controller`
- [Time](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/temporal-consciousness): boot skill · Provides cycle timing and elapsed-time awareness. · `Boros/boros/skills/temporal-consciousness`
- [Context](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/context-orchestration): boot skill · Loads manifest-derived context for the model. · `Boros/boros/skills/context-orchestration`
- [Memory](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/memory): boot skill · Pages context, archives commits, and searches stored memory. · `Boros/boros/skills/memory`
- [Loop orchestrator](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/loop-orchestrator): state machine · Advances cycle stages and persists loop state. · `Boros/boros/skills/loop-orchestrator`

### Capability skills

On-demand skills that handle work, reasoning, and communication.

- [Mission control](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/mission-control): task intake · Queues tasks and tracks mission status. · `Boros/boros/skills/mission-control`
- [Tool use](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/tool-use): execution tools · Performs terminal and file-edit operations. · `Boros/boros/skills/tool-use`
- [Reasoning](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/reasoning): cognition skill · Decomposes problems and evaluates options. · `Boros/boros/skills/reasoning`
- [Communication](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/communication): interaction skill · Broadcasts and listens within the agent substrate. · `Boros/boros/skills/communication`
- [Web research](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/web-research): research skill · Searches, browses, and archives external sources. · `Boros/boros/skills/web-research`
- [Scratchpad](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/scratchpad): working memory · Short-lived workspace for transient notes. · `Boros/boros/skills/scratchpad`

### Self-improvement

Reflection, mutation, evaluation, and rollback loop.

- [Reflection](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/reflection): evolution skill · Analyzes traces and writes hypotheses for improvement. · `Boros/boros/skills/reflection`
- [Meta-evolution](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/meta-evolution): mutation skill · Proposes, applies, and rolls back repository changes. · `Boros/boros/skills/meta-evolution`
- [Meta-evaluation](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/meta-evaluation): review skill · Reviews proposals and maintains evaluation criteria. · `Boros/boros/skills/meta-evaluation`
- [Eval bridge](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/eval-bridge): eval connector · Connects Boros to the external evaluation pipeline. · `Boros/boros/skills/eval-bridge`
- [Skill forge](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/skills/skill-forge): self-mod tool · Snapshots, validates, tests, applies diffs, and rolls back code changes. · `Boros/boros/skills/skill-forge`
- [Eval generator](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/eval-generator): external pipeline · Independent task/eval generation and execution pipeline. · `Boros/boros/eval-generator`

### Persistent state

Operational files, session state, logs, and snapshots.

- [Session state](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/session): persistence · Stores current cycle and loop state. · `Boros/boros/session`
- [Logs](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/logs): trace store · Cycle and operational logs for long-running continuity. · `Boros/boros/logs`
- [Memory store](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/memory): artifact store · Persistent score history and archived memory artifacts. · `Boros/boros/memory`
- [Commands](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/commands): control queue · Pending human/director commands. · `Boros/boros/commands`
- [Snapshots](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/boros/snapshots): rollback store · Saved repository states for recovery and rollback. · `Boros/boros/snapshots`

### Specs

Design-time documentation and architecture guidance.

- [Predev specs](https://github.com/asi-rishi/boros-architecture/tree/master/Boros/predev-specs): design docs · Architecture notes, skill specs, and build-order guidance. · `Boros/predev-specs`

## Connections

- Kernel → Manifest: reads · Bootstraps runtime from the declared manifest.
- Kernel → Config: loads · Applies runtime limits and logging settings.
- Kernel → Skill router: dispatches · Routes tool calls through the skill registry.
- Kernel → Model adapters: calls · Uses provider adapters as the model boundary.
- Kernel → Identity: boots · Loads identity early in startup.
- Kernel → Mode control: boots · Loads mode control early in startup.
- Kernel → Time: boots · Loads temporal awareness early in startup.
- Kernel → Context: boots · Loads context orchestration during startup.
- Kernel → Loop orchestrator: boots · Initializes the cycle state machine.
- Skill router → Memory: exposes · Makes memory tools available to the runtime.
- Skill router → Reflection: exposes · Makes reflection tools available to the runtime.
- Skill router → Meta-evolution: exposes · Makes mutation tools available to the runtime.
- Skill router → Meta-evaluation: exposes · Makes review tools available to the runtime.
- Skill router → Eval bridge: exposes · Makes evaluation bridge tools available to the runtime.
- Skill router → Skill forge: exposes · Makes self-modification tools available to the runtime.
- Skill router → Mission control: exposes · Makes task intake tools available to the runtime.
- Skill router → Tool use: exposes · Makes execution tools available to the runtime.
- Skill router → Reasoning: exposes · Makes reasoning tools available to the runtime.
- Skill router → Communication: exposes · Makes communication tools available to the runtime.
- Skill router → Web research: exposes · Makes research tools available to the runtime.
- Skill router → Scratchpad: exposes · Makes scratchpad tools available to the runtime.
- Loop orchestrator → Session state: persists · Stores cycle and stage progress in session state.
- Loop orchestrator → Logs: records · Writes cycle logs for later reflection.
- Reflection → Memory store: reads · Uses memory history and traces for hypotheses.
- Reflection → Logs: analyzes · Considers operational logs when reflecting.
- Reflection → Meta-evolution: feeds · Turns hypotheses into proposed changes.
- Meta-evolution → Skill forge: uses · Applies diffs, validates, tests, and rolls back through the forge boundary.
- Meta-evolution → Snapshots: writes · Captures rollback points and saved states.
- Meta-evolution → Loop orchestrator: updates · Can modify loop behavior as part of evolution.
- Meta-evaluation → World model: scores by · Evaluates changes against the scoring rubric.
- Meta-evaluation → Eval bridge: routes · Hands off review results to the eval bridge.
- Eval bridge → Eval generator: connects · Submits requests to the external eval pipeline.
- Eval generator → Meta-evaluation: returns scores · Feeds evaluation outcomes back to review and calibration.
- Mission control → Tool use: drives · Task intake leads to terminal and file operations.
- Mission control → Commands: reads · Consumes queued human/director commands.
- Tool use → Logs: traces · Operational actions are logged for continuity.
- Context → Manifest: derives · Builds context from the system contract.
- Memory → Memory store: pages · Moves persistent memory in and out of working context.
- Memory → Session state: uses · Relies on session artifacts for continuity.
- Predev specs → Skill router: specifies · Defines the intended skill topology and build order.
