AGENTS.md

AGENTS

Scope: repository-wide.

Working doctrine

• Product first.
• Use cases before architecture.
• Hotgraph before generation.
• Reduced state before raw repo spelunking.
• Bounded artifacts before grand rewrites.

Output style

• Always give one clean product one-liner.
• Use matrix grids when comparing options.
• Explain the why in plain terms.
• Prefer Pareto-frontier tradeoffs over absolute claims.

Local rule

This repo is the standalone product shell.

That means:

• external source repos are bootstrap intake, not the shipped boundary
• hotgraph/ is the bootstrap reasoning surface
• policy/, benchmarks/, api/, and ux/ are shipped product slices
• runs/ holds generated packets, benchmark outputs, and scorecards
• local glue here should stay thin and deterministic

Agent bootstrap rule

Fresh sessions should not infer the system from raw repo traversal first.

Start here:

1. run rtk ./bin/bvtctl bootstrap-context
2. read api/session_bootstrap.md
3. refresh live state with rtk ./bin/bvtctl context
4. interact through the single API surface via rtk ./bin/bvtctl "<question>"

Why:

• the canonical front door is the conversational API
• policy and lineage should arrive as hydrated context, not as guesswork
• manifests and receipts are the bounded action/proof surfaces

Operational rule:

• use context for live system position
• use bootstrap-context for reusable cross-session handoff
• use ask only when binding a bounded manifest to the turn
• do not start with broad repo spelunking unless the API/context path is insufficient

Generation rule

The sequence is:

1. update source registry
2. build hotgraph
3. inspect graph summary
4. decide local import target
5. generate bounded artifact

Do not skip step 2 unless explicitly forced.