Skip to content

AGENTS.md

Latest commit

 

History

History
70 lines (51 loc) · 3.67 KB

AGENTS.md

File metadata and controls

70 lines (51 loc) · 3.67 KB
Raw

AGENTS.md

Operating instructions for AI coding agents working in this repo. Read this and STRATEGY.md first, every session.

Working agreements

Parity firewall (load-bearing)

A new capability ships REST route + OpenAPI entry first. SDK and CLI wrappers follow where they earn their place, generated where possible; MCP stays golden-path only. Releases go out as changesets when ready.

Frozen periphery

index stacking/mempool extras, the stacks-SDK wallet half (except nonce coordination — supported, see packages/stacks/README.md), webhooks format expansion. Shipped code stays; no new investment, no docs prominence. Being on this list is never grounds to delete; that takes usage or dead-code evidence. Unfreeze requires a named external request. Nonce coordination is the carved-out exception: demand-validated (named external request), supported, documented.

Scope discipline

  • OSS /v1 reads are keyless on a loopback publish; INSTANCE_TOKEN gates writes and every /v1 request once the API is reachable past loopback. Hosted /v1 (api.secondlayer.tools) is keyed: Authorization: Bearer with an account key (sk-sl_*, env SECONDLAYER_API_KEY). Same prepaid credits as archive bootstrap. Do not add accounts on OSS. Do not add hosted keyless reads.
  • Cursor format and public /v1 envelope are 1.0 contracts; reorg/cursor tests are sacred.
  • Decoders read Streams' reader in-process; the HTTP Streams path is guarded by the HTTP == in-process parity test (packages/api/src/streams/decode-dogfood.test.ts). Do not break either. (The 11 classic decoders — packages/indexer l2 module — moved in-process; sbtc/pox5/bns still read over HTTP until their own pass.)
  • Never describe product surfaces as L1/L2/L3 layers in docs or comms — Stacks is itself a Bitcoin L2, so the terms confuse users. Say raw (Streams), decoded (Index), your schema (Subgraphs). This also extends to code: no identifier, env var, service, or table may start with l2/layer2. The decoder service is decoder (image secondlayer-decoder), the dir is packages/indexer/src/decode/, checkpoints are named decode.<event_type>.v<major>, and the checkpoint table is decoder_checkpoints.
  • No EVM/multi-chain. No new wallet-side primitives beyond nonce coordination (supported) and what's already frozen.

State machines

  • States = one const array in the owning package, mirrored by a DB CHECK.
  • Transitions = a defineMachine table next to the states (packages/shared/src/db/transition.ts).
  • Every status write goes through casTransition; null = lost race, log and stop. scripts/ci/status-writes.ts fails CI on new raw .set({ status: / SET status sites (baseline file; shrink it, never grow it).
  • Derived states ("is live", "is down", "caught up") = one exported pure fn, no inline copies.

Process

  • Work directly on main; push only when the founder asks (every push deploys prod).
  • Single-line conventional commits; no process labels; version bumps = chore: version packages.
  • Always create changesets for changed packages; release via bun run release.
  • Prefer delete over refactor when removing deprecated surfaces.

Voice (user-facing copy)

  • Calm infrastructure. Short declarative sentences.
  • No exclamation points, no emoji, no hype, no "vs Hiro" — generous to the ecosystem.
  • Technical precision over marketing language.

Decision rules

  • Reversible: decide, note it in the commit, move on.
  • Irreversible (cursor format, public API shape, pricing, product naming): explicit founder approval first.

If you change anything that contradicts this file or STRATEGY.md, update the doc in the same change. Stale instructions are worse than none.