git:20260301.8014ac4 to git:20260301.5d78289

1 added, 1 removed. Audit A to A.

---

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.

+ 5. **Process invocation is engine-owned** — All engines use `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)