universal-lsp CLAUDE.md

Universal LSP + graph-lite

One C++ language server for many languages (Lua-declared plugins, no external language-server processes), plus graph-lite — the embeddable graph library it runs on. Built for a terminal-first, agent-driven world; standard LSP for editors, MCP for agents.

Status: pre-implementation. Repo infrastructure, gates and docs are in place; build phase 1 (graph-lite core) is the current work. Scope: docs/spec.md.

This repo is AI-first. Agents write the code; humans review at the PR. Every rule below exists to make that loop fast and safe.

Response rules

• Execute. No preamble, no "I'll start by…", no restating the task.
• Lead with action or answer. Reasoning after, only if non-obvious.
• Batch independent tool calls. Read several files at once, grep in parallel.
• Never speculate about code you have not read. Read first.
• Disagree when the user is wrong. State the correction, once.
• Terse. Fragments fine. Commands, paths and code stay exact.
• End summary: 1–2 sentences.

Coding rules

• Fail fast, loudly. A crash on a bad assumption beats a wrong answer. Invalid config throws; it never silently degrades. Validate at the seam where the bad value enters, not three layers down.
• Optimize for the next debugger. Errors name the value, the seam, and the fix. One seam per invariant — one place to look, one place to fix.
• Simplicity. Minimum code that solves the stated problem. No speculative abstraction, no config knob nobody asked for, no error handling for impossible cases. Concrete first; introduce an interface when the SECOND implementation actually arrives.
• Surgical. Every changed line traces to the request. No drive-by reformatting. Match surrounding style.
• Verifiable done. Convert the task to a command that proves it. Bug → reproducing test first. Refactor → green before AND after.
• TDD is the working method here, not an aspiration. Write the failing test, then the code. This project has no UI to eyeball and no staging to poke: a test is the only thing that says "done".
• Ship the guard with the fix. A defect that can recur gets its mechanical guard — a test, an assertion at the seam, a scripts/lint/ rule — in the SAME PR. Prose telling the next agent to be careful is a bug report against tooling.
• Never ship a fix you know is wrong. Say so in one sentence and take the right path. Never silence a failing test, a warning, or a guard to get green — the guard is the asset. If the quick fix is chosen anyway, pin the known-bad behaviour with a test; never a bare TODO, nobody greps those.
• One path, replaced completely. No shims, no dual paths, no feature flags, no v2 beside v1. Public contracts (the LSP surface, MCP tool names, the graph-lite header, the persistence format) are the genuine exception — those are one-way doors; name them and think before shipping.