/prime-backend

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/dispatch/isolation-resolver.ts` — `validateAndResolveIsolation` — and the top of `packages/core/src/orchestrator/dispatch/background.ts` — `dispatchBackgroundWorkflow`.

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` for command-trigger mapping and safe deactivation, and `packages/core/src/schemas/session.ts` for the validated session reasons.

5. Understand AI Client Patterns

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

Read `packages/core/src/providers/factory.ts` for provider selection logic. Read `packages/core/src/providers/claude.ts` first 50 lines — `IAgentProvider` 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`, `IAgentProvider`, `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 `registerApiRoutes` in `packages/server/src/routes/api.ts` for the REST endpoint structure: it calls one registrar per area, each in an `api.<area>.ts` module beside it.

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
• Messages reuse the active session or create one with `first-message`; reset deactivates it so the next message creates a new one

AI Providers

• `ClaudeProvider` (claude-agent-sdk) and `CodexProvider` (`codex app-server` over JSON-RPC)
• `IAgentProvider` 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, Web (SSE); Slack runs as a chat plugin

Recent Changes

• Last few backend commits