CLAUDE.md

1# Instance AI — Development Guidelines
2 
3## Linear Tickets
4 
5- **Never set priority to Urgent (1)**. Use High (2) as the maximum.
6 
7## Engineering Standards
8 
9Follow `docs/ENGINEERING.md` for all implementation work. Key rules:
10 
11- **No `any`, no `as` casts** — use discriminated unions, type guards, `satisfies`
12- **Zod schemas are the source of truth** — infer types with `z.infer<>`, don't define types separately
13- **Shared types in `@n8n/api-types`** — event types, API shapes, enums
14- **Test behavior, not implementation** — test contracts, edge cases, observable outcomes
15- **Tools are thin wrappers** — validate input, call service, return output. No business logic in tools.
16- **Respect the layer boundaries** — Tool → Service interface → Adapter → n8n internals
17 
18## Architecture
19 
20Read these docs before starting any implementation:
21 
22- `docs/architecture.md` — system diagram, deep agent pillars, package responsibilities
23- `docs/streaming-protocol.md` — canonical event schema, SSE transport, replay rules
24- `docs/tools.md` — tool reference, orchestration tools, domain tools, tool distribution
25- `docs/memory.md` — memory tiers, scoping model, sub-agent memory
26- `docs/filesystem-access.md` — filesystem architecture, gateway protocol, security model
27- `docs/sandboxing.md` — Daytona/local sandbox providers, workspace lifecycle, builder loop
28- `docs/configuration.md` — environment variables, minimal setup, storage, event bus
29 
30## E2E Testing
31 
32Tests live in `packages/testing/playwright/tests/e2e/instance-ai/`.
33 
34### Local-build mode (no docker, no recording — hits real Anthropic API)
35 
36```bash
37cd packages/testing/playwright
38export ANTHROPIC_API_KEY=sk-ant-...
39pnpm test:local:instance-ai                  # full suite
40pnpm test:local:instance-ai --grep &quot;preview&quot; # single test
41```
42 
43Each run gets a random port + throwaway DB — safe to run in parallel, never
44touches `~/.n8n`. This mode does **not** record proxy expectations; it
45bypasses the proxy stack entirely and calls Anthropic directly.
46 
47### Recording expectations (docker required)
48 
49To record (or re-record) proxy expectations for CI replay, run in container
50mode with a real key. This captures LLM traffic + tool traces into
51`expectations/instance-ai/<test-slug>/`:
52 
53```bash
54pnpm build:docker   # from repo root — build the local n8n image first
55cd packages/testing/playwright
56ANTHROPIC_API_KEY=sk-ant-... pnpm test:container:sqlite tests/e2e/instance-ai --workers 1
57```
58 
59Commit the regenerated `expectations/` files alongside the test.
60 
61See `docs/e2e-tests.md` for the full recording/replay architecture.
62 
63## Key Conventions
64 
65- **Event schema**: `{ type, runId, agentId, payload? }` — defined in `streaming-protocol.md`
66- **POST `/chat/:threadId`** returns `{ runId }` — not a stream
67- **SSE `/events/:threadId`** delivers all events — replay via `Last-Event-ID` header or `?lastEventId` query param
68- **Run lifecycle**: `run-start` (first) → events → `run-finish` (last, carries status)
69- **Planned tasks**: `plan` tool for multi-step work; tasks run detached as background agents
70- **Sub-agents**: stateless, native domain tools only, no MCP, no recursive delegation
71- **Memory**: observational memory = thread-scoped, working memory is disabled
72