repos-expert: Instructions file for Claude Code

Working on repos-expert

This tool turns a folder of code repositories into a knowledge base an AI assistant can answer from. ARCHITECTURE.md explains the design; this file is about changing it safely.

Ground rules

TDD. Write the failing test first, watch it fail for the right reason, then implement. Tests build real git repositories in temp directories and inject fake agent runners — no network, no model calls, no mocking of git.

Never write to stdout in the MCP path. stdout is the protocol. A stray console.log in anything reachable from expert mcp corrupts the stream and breaks the client, usually with a confusing error. Diagnostics go to stderr.

Every subprocess call uses execFile with an argument array. No shell strings, ever. Repo names are validated against /^[A-Za-z0-9._-]+$/ before they reach a path or a command line — that check is what stops ../ from becoming a file read outside the folder.

URLs in repos.txt go through a transport allowlist (https, http, ssh, git, file, and the user@host:path form). It is an allowlist rather than a denylist because git's ext:: transport runs a shell command — a URL pasted from a chat window must not reach it. The derived folder name goes through the same name check as everything else.

Caps are load-bearing. 100 search matches, 2,000 lines / 200 KB per file read. They exist because results land in someone's context window, not for speed. Don't relax them without a reason that accounts for that.

Failure is per-repo. One repo failing to curate is collected and reported; the batch continues. A failed GitHub sync does not stop curation of what is already on disk. An empty folder produces instructions, not an error. Preserve this — it is the difference between a tool that works in a degraded environment and one that doesn't.

The curator is a model, and models are wrong sometimes

The knowledge docs are written by an agent. Two consequences the code must keep honoring: