stitchkit: Instructions file for Codex

stitchkit — agent guide

Contract-first backend framework for Bun and Node. One defineContract() → an HTTP API, MCP tools, AI-agent tools, a CLI and a typed client. What it is and is not: docs/PRINCIPLES.md.

📦 Building an app with stitchkit? Not this file: see the README, the guide, and in your project node_modules/stitchkit/llms.txt (it names the llms/<entrypoint>.txt slice to load per import) or skills/stitchkit copied into .claude/skills/.

🔧 Developing stitchkit? One rule per line, each linked to where its reasoning lives: ADRs in docs/decisions/, the rest in docs/architecture/. Setup, commands, hooks, local development against an app, PRs: CONTRIBUTING.md.

Before you change code

• Name the invariant (I1–I15) your change serves; nothing under "Not in stitchkit" ships. → PRINCIPLES
• NEVER ship a competing WebSocket or hook engine — wrap Socket.IO (createSocketIOClient / createSocketIOServer) and react-query-kit (createCursorQuery). → ADR 0008
• ALWAYS Zod-first: the schema is the source of truth, types come from z.infer; never hand-write a duplicate type. → PRINCIPLES I3
• NEVER write as in business logic. Casts live only at named boundaries — internal/typed.ts, executableAgentRuntimeTools in tools/runtime-tool.ts, adapters over untyped emitters (Socket.IO, event bus, cache bridge), the generic bridges in browser/client.ts — each with a comment saying why; elsewhere fix the types upstream. → ADR 0003, engineering-rules
• Transport and hooks use RuntimeContext (loose), handlers HandlerContext (typed); never cast between them. → ADR 0003
• ALWAYS keep the core Web Fetch-clean: createHandler takes HandlerConfig (no Bun types); Bun APIs live only in createServer and stitchkit/server. → ADR 0013
• ALWAYS keep the core generic — no domain model; scopes are free strings, no billing, source is transport-only. → ADR 0002
• NEVER make the project declaration a condition of a build, test, start path or check; stitchkit/declaration stays a leaf (packages/core/tests/project-declaration.test.ts). → ADR 0104
• ALWAYS make a declared option load-bearing and register the test that proves it in packages/core/tests/option-effects.test.ts. → I9, engineering-rules
• ALWAYS extend the owner that already exists: one implementation per job, one owner per public name, no alias, shim or parallel path. → ADR 0199, I8
• NEVER import agent-runtime/ from the core; the runtime may import the core, shared machinery goes to a neutral part (src/durability/). Every direction between parts of src/ is declared in packages/core/tests/import-graph.test.ts — declare a new one there. → ADR 0197
• NEVER publish a runtime internal because it looks useful: it leaves agent-runtime only when it needs no store and no run protocol, already exists proven by tests, and is typed against what the caller holds. → ADR 0142
• ALWAYS register every process a test starts with packages/core/tests/support/process-reaper.ts before it can exist; bun run test fails the run, naming the survivor, when one is left. → ADR 0249
• Keep functions ≤200 and files ≤500 lines (packages/core/tests/code-size.test.ts); an exception is a reasoned entry in packages/core/tests/fixtures/code-size-exceptions.json, and the list only shrinks. → ADR 0199
• Put an endpoint's tool options in the one tool group (tool: { name, view, ui, annotations, mcp }); expose stays outside it. → ADR 0196