codebrief

AI coding tools need project context. Most people paste random files or write Cursor rules by hand, so the model guesses the stack — wrong package manager, invented folders, “fixes” that fight the theme.

I needed a repeatable first draft of *what this repo is* that I would trust on my own products before asking anyone else to try it.

codebrief is a Node.js CLI that walks a repository and writes the always-on layer: CONTEXT.md, Cursor rules, and GitHub Copilot instructions. Zero npm runtime dependencies on purpose — one runtime, no plugin marketplace, no GUI.

The job is identity, not procedure. Always-on context should stay short enough that every chat can afford it. I use it on my own apps; if it cannot describe a repo I already understand, it is not ready.

No GUI and Node-only means a smaller audience than a VS Code extension, and a clearer install story. The generator will miss project-specific truths a scan cannot see — catalog paths, theme inversion, deploy host — so the workflow is generate, then edit three lines a stranger would need.

I deliberately did not stuff procedures into the same file. That is why skillbrief exists as a second package instead of one mega-rules dump.

Published on npm and used on my own products, including this site, before I asked anyone else to try it. Live download and version stats on the case study come from the npm registry when available — not invented counts.

One rules file that tries to answer both “what is this?” and “how do I work here?” gets longer every week and worse at both jobs.

Ship the identity layer first. Keep it editable. Measure success by whether an agent stops inventing a second stack — not by how many files the CLI emits. Longer write-up: Always-On Context vs On-Demand Skills on /writing.