New Gem Setup

Updated September 20, 2026

Open a gem crystl just created, and one dismissible line appears above the terminal: “this looks like a new project — set it up?” Click it and the agent already sitting in that shard gets a briefed job, not a blank prompt. It reads what’s there, asks what it can’t read, and says what it’s doing before it does it.

Two different offers

A gem you just created and a gem you’re pointing crystl at for the first time are different situations, and get different offers.

  • “this looks like a new project — set it up?” fires only for a folder crystl itself just made, through the New Gem panel. Clicking it starts the full setup pass below.
  • “this project is new to crystl — run the project optimizer?” fires for an existing project opened for the first time, through the path field, the folder button, a drag-drop, or crystl open. The project isn’t new, only new here, so writing instruction files from scratch would be presumptuous. This one just opens the project optimizer instead.

Both are one line, never a dialog, and never gate you from working. If a folder satisfies both, the setup offer wins.

What decides the path

The setup pass reads the gem before deciding what to ask of it.

Has code, or a manifest, or git history? It reads the optimizer’s findings and gets to work fixing what the repository can already answer.

Nothing to read? No source, no manifest, no history. Writing instruction sections against that would produce a wall of headings each saying “nothing here yet,” which is worse than no file at all. So the job changes from writing to asking.

The written-project branch

Before hand-authoring anything, the agent runs crystl bundle list, already filtered to the gem’s type, and tells you which starter kit fits and what it installs. With your approval it runs crystl bundle install, which writes the AGENTS.md/CLAUDE.md skeleton plus rules and skills, and never touches a file already doing that job.

With the skeleton in place, it layers this project’s own specifics on top: the real build and test commands, the conventions already visible in the code, the gaps the report named. No placeholders, no generic advice, no TODO lines left for you to fill in.

It says what it’s writing and why before it writes it, then opens the file in crystl’s own editor. You watch it happen instead of reading about it in scrollback.

The empty-project branch

There’s nothing to read, so the only thing worth asking about is the direction nobody has stated yet. The agent asks what the project is going to be, who it’s for, what finished looks like, and waits for your answer.

Once you’ve answered, it says which of the seven types that maps to and checks it sounds right before setting anything, never a guess you never confirmed. Setting the type also creates NORTH-STAR.md with just that one fact in it. The agent says so at the same moment, rather than letting you find the file later and wonder where it came from.

With the type set, it runs the optimizer again. The type decides which checks apply, so the gaps it reports now name the kit that fits. You install it by clicking; the agent never hand-scaffolds what a kit would install.

The direction conversation

In both branches, once the working part is done, the agent offers to run crystl northstar init as its own real question, not a footnote. The reason is stated every time. NORTH-STAR.md is what future feature decisions and reviews get checked against, so a rejected idea doesn’t get relitigated every time it comes back. On an empty project this direction is the only substance there is, so it’s the main thing on the table, not something to skip past.

You can say no. Nothing in this pass runs without you agreeing to it first.

What it never does

  • Never writes a section it can’t establish from the repository or from your answer. If there’s nothing worth writing, it writes nothing.
  • Never invents a build command, a convention, or a rejection you didn’t state.
  • Never sets your project’s type from a guess you haven’t confirmed.
  • Never gates starting work. The offer is one line, and skipping it costs nothing.
  • Never overwrites a file already doing the job a kit or a hand-written section would do.