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, isolationenvironments, workflowruns, 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