Gem Types

Updated September 20, 2026

Every gem has a project type. It says what the work there produces, and crystl uses it to decide what to ask of the project.

Point the optimizer at a gem holding finances or personal notes and, without a type, it reports a stack of failures: no testing commands, no build section, no commit guidelines. Every one of those absences is correct by design. The type is what stops crystl asking a notes folder for a test command.

The seven

Typing by subject runs forever, because subjects are unbounded: marketing, finances, relationships, and on. Typing by what the work produces closes.

Type Produces Absorbs
Code software that runs dev projects
Research answers, synthesis investigations, learning
Content published work for an audience marketing, writing
Records state tracked over time finances, health, inventory
Personal change in you or a relationship self-improvement, habits
Orchestration decisions and dispatch across other gems a meta gem that coordinates the rest
General anything the other six do not describe the escape hatch, and the default

It is a closed list. You pick one; there is no free-text box. The field does exactly one job, which is selecting a check set, and a typed string cannot select one. Free text would also fragment the field into fifty spellings of “dev project” until nothing could be built on it. What the gem is for, in your own sentences, goes in NORTH-STAR.md instead. Two fields describing the same thing eventually disagree.

General is load-bearing. Any fixed list is wrong for somebody, and forcing a bad fit produces worse signal than leaving it alone. A General gem is asked everything a Code gem is asked.

What a type changes

Three things, and nothing else.

Which optimizer checks run. A type that produces something other than software stops the build-and-test questions. In their place come the checks written for that kind of project: Research is asked for its sources, a synthesis file and a citation convention; Content for a drafts and published split, an audience section and a style file; Records for where the data lives, the entry format and how an entry is added; Personal for a dated log and the convention for writing in it; Orchestration for the seven files an orchestrator needs (index, roster, ordering, queue, capture, history, person).

Which starter kits you are offered. The kit shelf in the New Gem panel and the file library shows the kits written for the gem’s type. A Records gem is offered the Records kit rather than a list of code stacks.

How the direction file gets drafted. The type is put into the drafting prompt, so the six questions land in the right register. A Records gem tracking finances and a Code gem shipping software answer “what good looks like” in different words.

It never restricts capability. A Records gem can still run builds, spawn workers, and merge branches. The type scopes what crystl checks and asks, never what you or an agent may do.

Where it is stored

In NORTH-STAR.md, as one line near the top:

**Project type:** Records

Not app state. In the file it travels with the repository, so a Codex or Antigravity worker reading the project cold sees it, and a gem opened on another machine carries it.

Reading is tolerant and writing is exact. Write the line in your own hand, with different emphasis or as a list bullet or labelled “Gem type”, and crystl still reads it. When crystl writes one, it writes the shape above. Setting a type rewrites that one line and moves nothing else in the file. A project with no direction file gets a minimal one holding the type and a pointer to crystl northstar init, never a template of empty headings.

A gem with no direction file has no type, and no type is scored as General. Unset and “chose General” are different facts, which is why crystl says “no project type set” rather than printing General at you.

Setting it

Four places, and it is changeable at any time. A type set once at creation and frozen would be worse than no type.

  • the New Gem panel, when you create the gem;
  • gem settings, to correct one later;
  • the optimizer’s own picker, in the title row, for a gem with no type yet;
  • the terminal:
crystl gem type                 # what this gem is
crystl gem type set records     # set it

Every picker says what the choice changes, and says that the answer is saved to NORTH-STAR.md. Picking a type writes a file into your repository, so the click tells you that before you make it.

Detection

A gem crystl just created and one it looks new by content alone get different offers. See new gem setup for the full flow.

A folder crystl just made, still empty. The offer starts a setup pass. On a project with nothing to read, it asks you what the project is going to be and sets the type from your answer, confirming with you first. It gets every one of the seven types right this way, not only Code.

A project pointed at the New Gem panel’s path field, the file picker, gem settings, or the optimizer’s own row. Detection here is much more limited: the markers it reads are stack markers, Package.swift, package.json, Cargo.toml, so it can tell Code from not-Code and nothing else. A detected type arrives pre-selected so you confirm rather than choose, and every non-code project lands on General until you correct it by hand.

Honest scoring

Changing the type changes the score, so the number stops being comparable between gems. Two rules keep that from misleading you.

A skipped check scores half, not full. A check that did not run is unknown, not passed, so it keeps half of its weight. Score a skipped check as a pass and a Records gem would outscore a well-set-up Code gem by having less asked of it. One cap on top: a skipped check never costs more than the worst answer the real check could have given, so unknown never prices below the worst known.

The ceiling is disclosed next to the number. The report says it in two labelled lines, one for how many checks the run skipped and one for what this type can reach:

3 checks skipped in this run
a Records gem tops out at 73

Saying a check was skipped while quietly charging for it would be the report lying to you. The second line is what makes the first one honest.

The top scores: Code and General reach 94, Orchestration 75, and Research, Content, Records and Personal 73. Code does not reach 100 because the twenty-one role checks written for the other types are ruled out for it, and being ruled out is not free. That movement is deliberate, and it is on screen rather than hidden.

The two lines answer different questions, which is why they are two lines. The count is what this run did not ask, which can be smaller than everything the type rules out: a gem with no instructions file at all never got as far as most of them. The top score is a property of the type, and is what a gem of this kind reaches when it has done everything asked of it.

crystl optimize --json carries gem_type and checks_not_applicable, so an agent reading the score knows how many checks were behind it. It stays a type name and a count rather than a field per check, so the shape holds as checks come and go between releases.