kmp-lsp copilot-instructions.md

kmp-lsp — Agent & Copilot Coding Instructions

Deep reference material (source layout, architecture patterns, coding guidelines with examples, test conventions, Serena MCP workflow) lives in docs/agent-reference.md. Load that on-demand. This file is behavioral rules only.

Workflow

• Never commit directly to main. Always create a feature branch, push, and open a PR.
• PR merge workflow: commit → push → resolve ALL review threads via gh api graphql resolveReviewThread → re-request review → gh pr merge --squash --delete-branch.
• Stacked PRs: merge base first, rebase dependent, then cargo build && cargo test on main after.
• After merging, install the binary: cargo install --path . --force.
• Run tests after every change: cargo test. All tests must pass.
• Run clippy after every change: cargo clippy -- -D warnings. Must be clean.

Code Quality

• Rust types model behaviour — code should be obvious in retrospect.
• Reach for a type before reaching for a comment. When you feel the need to explain control flow — why a fallback exists, what a None/empty result means, which order branches run, whether a string is still a placeholder — first ask whether an enum, newtype, or struct would encode that meaning so the compiler carries it and the signature tells the story. Prefer enum Outcome { Resolved(T), KeepWalking } over Option<T> + a comment; prefer a ResolvedType that distinguishes concrete vs. generic over an is_generic(&str) sniff. Keep comments for irreducible domain knowledge (e.g. why apply means this = receiver), not for scaffolding the types should hold.
• No abbreviated names. Never use single-letter or short variable names like s, c, ty, rt, sym, loc, p, diags. Use full words: string, char, type, receiver, symbol, location, package, diagnostics.
• Explicit over clever. Split compound boolean expressions into named variables. Avoid chained combinators when a simple conditional is clearer.
• Every fix must include a test. If a bug slips through, the test should have caught it.
• Write tests that prove correctness, not just verify happy-path. Include competing/misleading definitions to catch regressions.
• and in a function name means it's doing two things. Split into two functions.
• Section comments inside a function body signal a split. Each phase becomes a named helper.