project-overview

name	project-overview
description	Complete project architecture and structure guide. Use when exploring the codebase, understanding project organization, finding files, or needing comprehensive architectural context. Triggers on architecture questions, directory navigation, or project overview needs.

BBot Project Overview

BBot is a pnpm monorepo for a self-bootstrapping AI coding agent and its runtime kernel. The repo is organized to keep the agent runtime, the kernel, and adapters separate but composable.

Repo Layout

• apps/: runnable applications (currently apps/bot-telegram).
• packages/: core libraries and runtimes.
• docs/: design notes, exec plans, runbooks, and PRD/roadmaps.
• infra/: infrastructure scripts/config.
• tooling/: shared tooling config.
• tests/: tests and fixtures.
• memory/: daily memory logs.
• Root identity/policy files: AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, HEARTBEAT.md, CLAUDE.md.

Key Packages

• packages/agent: LLM runtime and tool execution. Owns system prompt building, skills, compaction, MCP, and tool wiring.
• packages/omnicore: AI-native kernel with event sourcing, adapters, sessions, and supervisor.
• packages/shared: shared utilities (env/, logger.ts, paths.ts, restart.ts).

OmniCore Structure (Layered)

• packages/omnicore/src/domain: contracts and event types (domain/events.ts, domain/adapter-protocol.ts).
• packages/omnicore/src/infra: SQLite stores, migrations, projections, conversation context (infra/*.ts).
• packages/omnicore/src/runtime: kernel orchestration, reasoner, traits (runtime/kernel.ts, runtime/reasoner.ts, runtime/traits/*).
• packages/omnicore/src/transport: WebSocket adapter hub (transport/adapter-hub.ts).
• packages/omnicore/src/sdk: adapter client for external adapters (sdk/adapter-client.ts).
• packages/omnicore/src/entry: CLI, supervisor, local CLI adapter (entry/cli.ts, entry/supervisor.ts, entry/cli-adapter.ts).

Agent Package Structure

• packages/agent/src/system-prompt.ts: system prompt assembly and usage stats.
• packages/agent/src/skills.ts: skill discovery + prompt formatting.
• packages/agent/src/tools/: built-in tools wiring.
• packages/agent/src/mcp/: MCP tool integration.
• packages/agent/src/compaction/: context compaction prompts + logic.

Apps

• apps/bot-telegram: Telegram adapter app that connects to OmniCore over WebSocket.

Data and Runtime

• OmniCore stores data in .omnicore/omnicore.db (SQLite event log, config, projections).
• Sessions read AGENTS.md from the session root path.

Navigation Tips

• Start with packages/omnicore/README.md for runtime usage.
• packages/agent/src/index.ts shows how system prompt + tools + skills are wired.