indifferentketchup
93d3f86c2b
Ship Paseo-equivalent provider snapshot, AgentComposerBar, ACP dispatch rewrite with streaming/persist, permission prompts, and agent commands. Follow-up: pane-scoped chat resolution, CoderMessageList tool timeline, WS user-delta replace, and inference orphan tool_call stripping. Archive openspec v2-2; update CHANGELOG and CURRENT. Co-authored-by: Cursor <cursoragent@cursor.com>
110 lines
5.0 KiB
Markdown
110 lines
5.0 KiB
Markdown
# 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)
|
||
|
||
```bash
|
||
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.
|