kyleandClaude Opus 5
fa9d78366e
docs/design.md is the kickoff pack as written: design brief, session 1 prompt, and milestone outline. Committed unmodified so later edits to the brief show up as diffs. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
81 lines
4.5 KiB
Markdown
81 lines
4.5 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## Current state
|
||
|
||
Boxmaker is a sovereign personal agent harness written in Rust. As of this file's creation the
|
||
repo holds only `docs/design.md`: no code, no Cargo workspace, no Makefile, and no git history.
|
||
Work proceeds one milestone per session (M0–M7, table in `docs/design.md` Part 3). Before doing
|
||
anything, check which milestone artifacts exist (`spike/`, `docs/inference-contract.md`,
|
||
`AGENTS.md`, `Cargo.toml`) to work out where the project is.
|
||
|
||
`docs/design.md` is the binding design brief. Part 1 is the design; Part 2 is the session 1 prompt
|
||
(M0 spike plus M1 skeleton); Part 3 is the milestone table and the per-milestone prompt template.
|
||
If the brief looks wrong or conflicts with a measurement, stop and say so. Don't work around it.
|
||
Propose changes to `docs/design.md` as their own commit before building on them.
|
||
|
||
Once they exist, read `AGENTS.md` (project standards, how to run the gate, how to verify against
|
||
straylight) and `docs/inference-contract.md` (M0 measurements) alongside the brief.
|
||
|
||
## Commands (planned in M1, not yet present)
|
||
|
||
- `make gate` runs `cargo fmt --check`, clippy with warnings denied, `cargo test`, `cargo-deny`,
|
||
and a check that fails on any source file over 500 lines. Run it before calling any work done,
|
||
and report the exit status and last lines.
|
||
- Single test: `cargo test -p <crate> <test_name>`.
|
||
- `bxctl` is the owner CLI (`bxctl chat` from M2, `bxctl reindex` from M5).
|
||
|
||
## Architecture in brief
|
||
|
||
Separate binaries in one Cargo workspace. Each role holds as little authority as possible:
|
||
|
||
- `loopd` owns sessions, prompt assembly and memory. It has no credentials and no network. Its
|
||
only I/O is Unix sockets to `gatewayd`, `brokerd` and `inferproxy`.
|
||
- `brokerd` is the only place authority lives. It reads owner-written grants (it cannot write
|
||
them), runs each approved tool call in a fresh rootless container, and writes a hash-chained
|
||
JSONL audit log.
|
||
- `gatewayd` is the Mattermost channel. Outbound only, no listening port; approvals arrive as
|
||
replies or reactions over the WebSocket.
|
||
- `inferproxy` is a ~100-line byte forwarder to `llama-server`. Drop it if M0 shows
|
||
`llama-server` can serve a Unix socket on the same host.
|
||
- `proto` holds shared types. `toolkit` holds tool container entrypoints.
|
||
|
||
Structural rules that span crates:
|
||
|
||
- No crate depends on another role's crate. Crates depend only on `proto`.
|
||
- Authority is encoded in types. A tool can't run without a `Decision`, and only `brokerd`'s
|
||
policy module can construct one (covered by a compile-fail test).
|
||
- No source file over 500 lines.
|
||
- Files are the source of truth (`sessions/`, `memory/`, `grants/`, `audit/`). SQLite is only
|
||
for rebuildable indexes and queues.
|
||
|
||
## Inference contract (the constraint most likely to be broken by accident)
|
||
|
||
Prompt processing on straylight is slow, and the hybrid-attention model can't partially rewind
|
||
its KV cache, so any change to an earlier byte of the prompt forces an expensive full re-read.
|
||
|
||
- Each turn's request must be a strict extension of the previous one. Volatile content (time,
|
||
heartbeat notes, memory refreshes, recalled memory) goes only in the newest message, never in
|
||
the system prompt or earlier history.
|
||
- Tool results are size-capped when first appended and never trimmed later.
|
||
- The baseline (system prompt, tool schemas, `memory/core.md`) stays at 3,000 tokens or less,
|
||
measured with the server's tokenizer. Extra tool schemas are added through `find_tool`, not
|
||
put in the baseline.
|
||
- Compaction happens only when the session is idle, and starts a new epoch
|
||
(`sessions/<id>/<epoch>.jsonl`). Old logs are kept.
|
||
- Main session, subagents and scheduled jobs each use their own server slot.
|
||
- Streaming always. Timeouts are "no bytes for N seconds", never total deadlines.
|
||
|
||
## Working rules from the brief
|
||
|
||
- Verify every external crate API on docs.rs, and every llama-server or Mattermost request field
|
||
against primary docs, before use. Crate names and server parameters in the brief come from
|
||
memory and aren't verified. If you can't fetch the docs, say so; don't guess.
|
||
- Keep dependencies few. Justify each in `docs/dependencies.md`. Any outbound call must be listed
|
||
in `docs/egress.md`. No telemetry and no update checks.
|
||
- If a feature isn't in the brief, propose it; don't build it. Stay inside the current
|
||
milestone's scope.
|
||
- Write tests first. Make one logical change per commit. Never commit runtime data, secrets, or
|
||
spike output that contains conversation content.
|