boocode/AGENTS.md

Agent navigation

Cursor/agent entry point for the BooCode monorepo. Deep engineering reference: CLAUDE.md (Claude Code). This file is navigation + task routing only.

Last updated: 2026-05-25

Doc map

Need	Read
Commands, gotchas, inference, DB, env	CLAUDE.md
Read-only chat behavior	BOOCHAT.md
Write tools, dispatch, pending changes	BOOCODER.md
Shipped vs planned, version order	boocode_roadmap.md
Latest release truth	CHANGELOG.md (top entry = current)
System diagram + data flow	docs/ARCHITECTURE.md
Current focus / blockers	CURRENT.md
Batch convention	openspec/README.md
Shipped batch snapshots	openspec/changes/archived/
Chat agent personas + tool lists	data/AGENTS.md
External repo lift inventory	boocode_code_review.md

Monorepo layout (actual)

Three surfaces, four packages. There is no apps/chat/ directory.

Surface	Packages	Port	Deploy
BooChat	apps/server (API + inference) + apps/web (SPA)	100.114.205.53:9500	Docker boocode container
BooTerm	apps/booterm	100.114.205.53:9501	Docker booterm container
BooCoder	apps/coder	host :9502	systemd boocoder.service (not Docker since v2.1.0)

Shared: Postgres 16 — Docker service boocode_db, database name boochat, host port 127.0.0.1:5500.

Task routing

Task type	Start here
Chat inference / tools / compaction	apps/server/src/services/inference/
WS frames	apps/server/src/types/ws-frames.ts + apps/web/src/api/ws-frames.ts (keep in sync)
Frontend chat UI	apps/web/src/components/, hooks in apps/web/src/hooks/
BooCoder write tools / dispatch	apps/coder/src/ — build server first (pnpm -C apps/server build)
Provider picker / external agents	apps/coder/src/services/provider-registry.ts, dispatcher.ts, agent-probe.ts
Terminal panes	apps/booterm/src/, frontend TerminalPane.tsx
Schema changes	apps/server/src/schema.sql + sync *_STATUSES in apps/server/src/types/api.ts
New batch / feature	openspec/changes/<slug>/proposal.md + tasks.md (see below)

Verification (before claiming done)

pnpm -C apps/server test && pnpm -C apps/server build
npx tsc -p apps/web/tsconfig.app.json --noEmit   # root tsc can miss web errors
curl http://100.114.205.53:9500/api/health       # Tailscale IP, not localhost:9500
curl http://100.114.205.53:9502/api/health       # BooCoder on host

Deploy truth beats source-only reads — check running health + git log --oneline -3.

Hard rules (from CLAUDE.md)

• Do not commit or push unless Sam explicitly asks.
• No app-layer auth — Authelia at the reverse proxy.
• Parts table is source of truth — read message tool fields from messages_with_parts view, write via insertParts.
• New WS frame type — update server + web schemas; publish via publishFrame / publishUserFrame only.
• New tool — own file in services/, register in tools.ts ALL_TOOLS; whitelists derive from there, never hardcoded.
• Typecheck web with per-app tsconfig — root tsc --noEmit uses project references and can miss errors.
• includeUsage: true on createOpenAICompatible in provider.ts — do not remove.
• Agent dispatch — direct spawn/exec on host via install_path (v2.1.0+); SSH helpers deprecated.
• Event dedup — server publishes via broker; frontend must not duplicate sessionEvents.emit after API calls that already WS-broadcast.

Using openspec with Cursor

Openspec is a folder convention, not a CLI. Use it to give agents a scoped brief before coding.

When starting a batch

1. Create openspec/changes/<slug>/ (lowercase-hyphenated, e.g. v2-2-arena-ui).
2. Write proposal.md — why, scope, non-goals, dependencies.
3. Write tasks.md — numbered checkbox steps (build + smoke).
4. Optional design.md — schema/API decisions that outlive the batch.

See openspec/README.md for the full shape. Shipped pre-v1.13.15 batches live in openspec/changes/archived/ as snapshots only.

Prompting an agent

@openspec/changes/<slug>/proposal.md @openspec/changes/<slug>/tasks.md
Implement tasks 1–3. Server tests must pass. Do not commit.

Attach the spec files with @ so they load into context. Point at specific code paths when known:

@openspec/changes/v2-x/proposal.md
Extend apps/coder/src/routes/providers.ts — follow provider-registry.ts patterns.

After shipping

• Tag: vMAJOR.MINOR.PATCH-slug
• Add entry to top of CHANGELOG.md
• Move or snapshot the openspec folder to archived/ if you want history preserved
• Update CURRENT.md and boocode_roadmap.md shipped table if the batch was roadmap-tracked

What not to use openspec for

• One-line bug fixes — just describe the bug + file.
• Exploratory questions — Ask mode + @CLAUDE.md is enough.
• Duplicating CLAUDE.md — openspec is per-batch scope, not permanent conventions.