In Part 0 I laid out the philosophy behind mini: keep state thin, send Claude only the essentials, and let tested TypeScript — not the model — own the project state. Now we start building.
Across this series we'll work on one small running example: pycalc, a command-line calculator in Python. It's deliberately a boring domain — that way the spotlight stays on mini, not on the math. This part is about the very first command: mini init.
What init actually does
mini init creates a new project. It asks four questions and writes two files into a .mini/ directory. That's it — no scaffolding of your source code, no opinions about your stack. It only sets up mini's state.
mkdir pycalc && cd pycalc
mini init
The four questions are: name, what you're building, for whom, and the constraints. For our calculator:
- Name: pycalc
- What: A small command-line calculator
- For whom: People who want quick arithmetic in the terminal
- Constraints: Python 3, standard library only
Prefer it non-interactive? Every answer has a flag:
mini init --apply \
--name "pycalc" \
--what "A small command-line calculator" \
--for-whom "People who want quick arithmetic in the terminal" \
--constraints "Python 3, standard library only"
The two files it writes
project.md — one page, by hand if you want
This is the human-readable heart of the project: what you're building, for whom, and the constraints. One page, on purpose. It's the file that gets sent to Claude as context, so every extra paragraph is tokens you'll pay for on every phase.
pycalc
A small command-line calculator.
For: People who want quick arithmetic in the terminal.
Constraints: Python 3, standard library only.
You can edit project.md by hand anytime — it's just markdown. Keep it tight.
state.json — a lightweight header
The second file is the machine state. Right after init it's nearly empty — no phases yet — but it's the index that everything else hangs off: phase list, statuses, and the model choices per step.
The important design decision: state.json is only a header. When phases arrive later, their detail (steps, reports) won't bloat this file — it lives separately in .mini/phases/phase-{id}.json and loads only when needed. That separation is what keeps mini's context footprint small as the project grows.
Starting inside an existing project
pycalc is greenfield, but init is just as happy in a directory that already has code. When it detects existing source, it offers to run mini audit at the end — a pass that builds a codebase.md overview so later Claude sessions can orient themselves without re-reading your whole src/. We'll cover that path properly in Part 2.
What you have now
After init, your project looks like this:
pycalc/
└── .mini/
├── project.md # one page: what, for whom, constraints
└── state.json # lightweight header: phases, statuses, models
No phases, no plans, no code yet — just a clean, minimal foundation. That's the point: mini doesn't ask you to think about the whole roadmap up front. You define what you're building in one page, and decide the next step when you get there.
And deciding the next step is exactly what mini next is for.
Next up: Part 2 — onboarding an existing project with import-gsd, audit, and map.
Want to try it now? mini is free and open source (MIT):
cd your-project
npx mini-orchestrator install-commands
Top comments (0)