GolemBot — Project Conventions for Claude Code

This file is the Claude Code equivalent of .cursor/rules/*.mdc. It is auto-loaded at conversation start and provides project-level constraints.

Architecture Hard Constraints

When modifying code under src/, the following constraints must not be violated.

Things You Must Never Do

1. Don't do what the Agent should do — GolemBot 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, name, and infrastructure settings.
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 verified across server.ts, gateway.ts, and cli.ts.
• Any change to the AgentEngine interface (engine.ts) must remain compatible with all engines (Cursor, Claude Code, OpenCode, Codex).
• StreamEvent type changes must verify compatibility with server.ts SSE output, cli.ts event handling, and gateway.ts IM message assembly.

File Responsibility Boundaries

Concurrency Model

• chat() calls with the same sessionKey must be serialized (KeyedMutex).
• Different sessionKeys can run in parallel.
• Do not introduce global locks.

Testing Conventions

Feature Changes Must Be Verified

Any substantive change to source files under src/ must:

1. Add dedicated tests for the new functionality — passing existing tests is not enough.
2. Run pnpm run test to ensure all unit tests pass.
3. Run pnpm run build to ensure TypeScript compiles.

Unit Tests (vitest)

Location: src/__tests__/<module>.test.ts

Mock Engine Pattern — Unit tests do not call the real Agent. Replace with a mock engine:

async function* mockInvoke(prompt, opts): AsyncIterable<StreamEvent> {
  yield { type: 'text', content: 'mock response' };
  yield { type: 'done', sessionId: 'mock-session-123' };
}

Inject via vi.mock('../engine.js', ...), returning mock engine from createEngine.

Running

pnpm run build        # TypeScript compile
pnpm run test         # Unit tests (vitest)

Engine Implementation Notes

Claude Code

• Binary: ~/.local/bin/claude
• Flags: -p <prompt> --output-format stream-json --verbose --dangerously-skip-permissions
• --verbose is required for intermediate stream events
• Auth: claude auth login or ANTHROPIC_API_KEY env var

Cursor

• Binary: ~/.local/bin/agent
• Flags: --output-format stream-json --stream-partial-output --force --trust --sandbox disabled --approve-mcps
• Uses segmentAccum dedup for --stream-partial-output summary events

OpenCode

• Binary: opencode (on PATH)
• Flags: run <prompt> --format json
• step_finish events are accumulated; single done event emitted on process close

Codex

• Binary: codex (npm: @openai/codex)
• Flags: exec --json --full-auto --skip-git-repo-check [--model X] <prompt>
• Resume: exec resume --json --full-auto --skip-git-repo-check [--model X] <thread_id> <prompt>
• Auth: CODEX_API_KEY env var (also sets OPENAI_API_KEY for compatibility)
• --skip-git-repo-check is required (GolemBot uses temp dirs)