Find what is missing from any project, then fix it

AI agents are only as good as the instructions and direction you give them. But keeping that complete and consistent is hard to do by hand, especially as a project grows. The project optimizer scans your project and surfaces exactly what's missing or needs attention.

It starts by asking what kind of project this is: Code, Research, Content, Records, Personal, Orchestration, or General. That choice, saved as one line in NORTH-STAR.md, scopes which checks run — a Records gem is never asked for a test command, and a Code gem is never asked for a citation convention. A check your project's type rules out costs nothing, so every type of project can reach the same 100 and two projects' scores are finally comparable. Findings run across four weighted categories (content, files, code, setup), each ranked by severity. You can also export the full report as a prompt for your agent to act on directly.

Every finding is labeled structure or substance. Structure is a missing file or an unwired section — a starter kit clears it. Substance is what your build command actually is, what your project is actually for — no kit can write that for you. The score says both: "3 structure gaps, 2 things only you can fill in." A check crystl genuinely couldn't measure still counts against you, but it's capped so not knowing never costs more than the worst real answer would have.

crystl can now fix many findings for you. Files over your own stated size limit, a .claude/settings.json that won't parse, an instruction-file import loop, missing permission rules, and a credential sitting in a public file all come with a scoped prompt crystl hands straight to the agent already running in that gem. A couple of others — a CLAUDE.local.md or settings.local.json git would otherwise commit — get fixed with one line crystl appends to .gitignore itself, no agent needed.

No NORTH-STAR.md yet? The create north star button hands your agent a drafting conversation: it reads the repo, proposes what the project is for and who it serves, and asks you to correct it. Nothing is written until you approve it.

The checks keep growing with real use: whether your instructions say which files are generated, whether there's a command for running just one test instead of the whole suite, whether a long instructions file points outward instead of loading everything at once, whether a build-output directory like node_modules is actually gitignored, and whether a monorepo's sub-applications have anything for an agent to read at all. Code and General projects now get a place for their own documents too — specs and runbooks for Code, a plain docs/ folder for General.

The Explore tab gives you a directory-level view of every agent instruction file across your project. Browse into any folder, see what's covered, and add new ones right where they're needed, so coverage grows alongside the work.