---
description: Prime agent with Archon backend (core + server) context
---

# Prime Backend: Core and Server Orientation

## Objective

Orient on the backend packages (`packages/core/` and `packages/server/`) before working on
server logic, orchestration, AI clients, slash commands, or API routes.

## Process

### 1. Understand the Core Package Structure

!`ls packages/core/src/`

### 2. Understand Message Flow (Orchestrator)

Read `packages/core/src/orchestrator/orchestrator-agent.ts` — the single entry point for all
platform messages. Maps messages to slash commands (via command-handler) or AI execution. Note
the lazy logger pattern and MAX_BATCH constants.

Read `packages/core/src/orchestrator/orchestrator.ts` first 60 lines — `validateAndResolveIsolation`
and `dispatchBackgroundWorkflow` utilities called by orchestrator-agent.

Read `packages/core/src/orchestrator/prompt-builder.ts` first 40 lines — how system prompts
are assembled with codebase context.

### 3. Understand Slash Command Routing

Read `packages/core/src/handlers/command-handler.ts` first 80 lines — deterministic command
dispatch (no AI). Note the full list of supported slash commands.

### 4. Understand Session State Machine

Read `packages/core/src/state/session-transitions.ts` in full — `TransitionTrigger` union type,
`TRIGGER_BEHAVIOR` record (creates / deactivates / none), and session lifecycle rules.

### 5. Understand AI Client Patterns

List clients:
!`ls packages/core/src/clients/`

Read `packages/core/src/clients/factory.ts` for provider selection logic.
Read `packages/core/src/clients/claude.ts` first 50 lines — `IAssistantClient` implementation
with streaming event loop pattern.

### 6. Understand Database Layer

List DB modules:
!`ls packages/core/src/db/`

Read `packages/core/src/types/index.ts` (or the main types file) first 60 lines for key
interfaces: `IPlatformAdapter`, `IAssistantClient`, `Conversation`, `Session`.

### 7. Understand the Server

Read `packages/server/src/index.ts` first 80 lines — adapter wiring, port allocation logic
(worktree auto-port in 3190–4089 range), Hono app setup.

List API routes:
!`ls packages/server/src/routes/`

Read `packages/server/src/routes/api.ts` first 60 lines for REST endpoint structure.

### 8. Check Recent Backend Activity

!`git log -8 --oneline -- packages/core/ packages/server/`

## Output

Summarize (under 250 words):

### Message Flow
- Platform → `handleMessage()` → orchestrator-agent → command handler OR AI client
- How ConversationLockManager gates concurrency
- Lock statuses: `started` / `queued-conversation` / `queued-capacity`

### Session Lifecycle
- `TransitionTrigger` values and their behaviors
- Only `plan-to-execute` immediately creates a new session; others deactivate first

### AI Clients
- `ClaudeClient` (claude-agent-sdk) and `CodexClient` (codex-sdk)
- `IAssistantClient` streaming pattern: `for await (const event of events)`

### Key Database Tables
- conversations, sessions, codebases, isolation_environments, workflow_runs, workflow_events, messages

### Server
- Port allocation: 3090 default, auto-allocated worktree ports
- Adapters wired: Telegram, GitHub, Discord, Slack, Web (SSE)

### Recent Changes
- Last few backend commits