Building with mini, Part 9/9 (finale): Onboarding a running project — import-gsd, audit, map

Eight parts, the whole command set: from init through the loop, autonomous mode, state and health. But the whole time we built pycalc from scratch — mini init on an empty directory, phase by phase. We skirted one scenario: what if a project is already running and you want to bring mini into it after the fact? There are three commands for that. And because it's the finale, at the end we'll open pycalc on GitHub.

For the onboarding I'll use a second, fresh example — notekeep, a small existing note-keeper CLI that has its own GSD-style planning folder (.planning/) and a few lines of code. Exactly the situation mini arrives into from the outside.

import-gsd — from a GSD roadmap into mini

When a project already has a plan in GSD structure (.planning/PROJECT.md, .planning/ROADMAP.md, phases), import-gsd extracts a skeleton from it:

cd notekeep
mini import-gsd

Reading the GSD project and building a summary (~30-60s)…
  (47.9k tokens · 482 output · 38.0k from cache · ~$0.112 in API)

Import: notekeep
  A tiny command-line note keeper that appends timestamped one-liner notes…
  For whom: terminal users who want to jot a quick note without leaving the shell
  Constraints: Python 3, standard library only, single-file script

  Phases: 6 (done: 2, doing: 1, todo: 2, skipped: 1)

  Preview:
    1. [done] Storage layer
    2. [done] add command
    3. [doing] list command
    4. [proposed] search command
    … and 1 more

Claude reads the planning files, summarizes the project, and converts the roadmap into mini phases — including the status mapping: GSD completed → done, in progress → doing, pending → proposed, cancelled → skipped. After you confirm, a .mini/ is created with the whole history:

mini status

Phases:
  [done]       1. Storage layer
  [done]       2. add command
  [doing]    > 3. list command
  [proposed]   4. search command
  [proposed]   5. delete command
  [skipped]    6. TUI browser

Suddenly the project is in mini, phase 3 is in progress (exactly as the ROADMAP said), and you can carry on with the loop from Part 4. Mind the scope: import-gsd is narrow — it only handles a GSD .planning/. When you have a plain project without one, you go through mini init (describe it) and then the pair below.

audit — so Claude understands code it didn't write

import-gsd brings over the plan, not an understanding of the code. That's what audit is for: it walks the existing sources and writes an overview into .mini/codebase.md:

mini audit

Going through the code and updating .mini/codebase.md…
  (52.8k tokens · 1 296 output · 40.3k from cache · ~$0.151 in API)
[ok] .mini/codebase.md updated.
  You can add your own notes to the file — the next audit will keep them.

The result is a structured map for Claude — what the project does, the directory structure, the key modules and functions, the technologies used:

# notekeep — code overview

## Overview
CLI note keeper, Python 3, standard library only. Appends timestamped one-liner
notes to a plain text file `~/.notekeep`…

## Key modules
- `notekeep.py` — entrypoint + all logic. Functions:
  - add_note(text) — …

The point: the later steps (plan, do) get this overview, so Claude doesn't start "blind" in an unfamiliar codebase. Two things to know: audit is the only onboarding step that costs tokens (it's a real Claude read of the code — here about $0.15), and you can add your own notes to the file — the next audit keeps them.

map — the machine map, for free

audit writes prose for Claude; map builds a machine map — for each source file a list of its exports, into .mini/graph/ plus the index .mini/graph.json:

mini map

Mapping TS/PHP/Rust/Python/Go/Java/C#/Kotlin/Swift/Ruby/C/C++ files…
[ok] .mini/graph/ + .mini/graph.json: 1 file.

No Claude, pure TypeScript — zero tokens, instant. mini uses it internally to quickly find where things are without reading whole files. It's a derivative of the sources (which is why graph/ is in .gitignore — it regenerates any time), so you don't version it; run it whenever the code moves.

Onboarding in three steps: import-gsd (or init) brings the plan → audit gives Claude understanding → map builds fast navigation. Then the project runs the same loop as a greenfield one.

Finale: pycalc goes public

And now the thing the series existed for. The whole time we built pycalc — a small calculator — not for the calculator's sake, but as a living showcase of .mini/. That directory is now open on GitHub, and it isn't "yet another calculator": it's the entire series made concrete, in the files you watched come to life:

• project.md — the vision we shaped in Part 2 (approach, non-goals, success criteria)
• todo.md — the backlog from Part 3, two open "v2" items
• discuss/phase-002.md — the parser decisions from Part 5 (AST vs. inline, error positions)
• run/phase-003.md — the run report with ## Verify findings from Part 5 (prefix, tab caret, usage)
• memory/phase-*.md — the phase memories that carried context between rounds
• codebase.md — the overview we just generated with audit
• state.json — five commits of history, four closed phases

Open it and read .mini/ next to the commit history: you'll see how lean state holds an entire project — a few pages of metadata, no documentation pile. That was the point from Part 0: keep minimal state, and send Claude only the essentials.

What the whole series showed

Nine parts, one tool, one calculator. mini isn't "yet another orchestrator" — it's a bet that a project's state belongs in tested code and one page, not in a growing pile of markdown you pay tokens for every session. pycalc is the proof that it holds: from init to four finished phases, the state never broke from a hallucination, because a hallucination never held it.

Thanks for reading this far. mini and pycalc are both out there — take them, break them, make them better.

pycalc on GitHub

---

mini is open source: npm install -g mini-orchestrator, then mini install-commands in your project. Source and docs on GitHub.