architecture-constraints git:20260301.8014ac4A

Immutable. This exact content never changes and is served at /api/v1/blob/7805245f634bab59.

---
description: Golem architecture hard constraints — must check before modifying any src/ code
globs: src/**/*.ts
alwaysApply: false
---

# Architecture Hard Constraints

When modifying code under `src/`, the following constraints must not be violated. To relax them, first update docs/architecture.md.

## Things You Must Never Do

1. **Don't do what the Agent should do** — Golem does not manage context window, dispatch tools, reason, or set session TTL. All "intelligent" behavior is delegated to the underlying Coding Agent.
2. **Don't add new core concepts** — The framework has only two concepts: assistant directory + Skill. Do not introduce Tool, Blueprint, Registry, Pipeline, or other abstractions.
3. **Don't put CLI logic in the core library** — `cli.ts` is a thin shell; it only parses arguments and formats output. All business logic must live in `index.ts` / `workspace.ts` / `engine.ts` / `session.ts` / `server.ts`.
4. **Don't declare Skills in config** — The `skills/` directory is the single source of truth. `golem.yaml` only configures engine and name.
5. **Process invocation is engine-owned** — Cursor Agent must be invoked via PTY (node-pty); Claude Code uses standard child_process.spawn. Do not assume invocation style outside the engine.

## Interface Change Rules

- Any signature change to the `Assistant` interface (`index.ts`) must be reflected in docs/architecture.md Chapter 5 (API definition)
- Any change to the `AgentEngine` interface (`engine.ts`) must be reflected in docs/architecture.md Chapter 7
- `StreamEvent` type changes must verify compatibility with `server.ts` SSE output and `cli.ts` event handling

## File Responsibility Boundaries

| File | Responsibility | Should Not Contain |
|------|-----------------|--------------------|
| `index.ts` | Public API, concurrency locks, orchestration of workspace/engine/session | Engine implementation details, HTTP logic |
| `engine.ts` | Engine interface, Cursor / Claude Code implementations, stream-json parsing, Skill injection | Session management, config loading |
| `workspace.ts` | golem.yaml read/write, skills scanning, AGENTS.md generation | Engine invocation, session management |
| `session.ts` | Session persistence (indexed by sessionKey) | Any other logic |
| `server.ts` | HTTP service, SSE, auth | Engine implementation details |
| `cli.ts` | Argument parsing → call core API → format output | Business logic |

## Concurrency Model

- `chat()` calls with the same `sessionKey` must be serialized (KeyedMutex)
- Different `sessionKey`s can run in parallel
- Do not introduce global locks (Phase 1 Mutex has been replaced with KeyedMutex)