Bootstrap Michi

In short

You have a project and you want to start using Michi. Bootstrap is the one-time setup that makes everything else possible — doc structure, conventions, the artifacts planning and sessions depend on. Run it before your first epic.

The flow is procedural: survey → recommend → execute. The agent reads your project, proposes an effort tier, then drafts each document with you for review. For greenfield projects — new or near-empty — it scaffolds everything from scratch. For brownfield, you pick a tier (S through XL) and defer the rest to a roadmap.

Bootstrap ends when the docs exist. Nothing is planned, nothing is scoped — that’s /michi-planning’s job. Bootstrap just makes planning possible.

Run /michi-bootstrap to start.

A sample session

A bootstrap session is short — survey, two questions, confirm, done. Here’s the shape:

You: I want to start using Michi on my recipe app — it has a README and a few planning notes, nothing else.

Agent: Got it. I’ll start with Phase 1: surveying the project.

[the agent reads the repo — file count, languages, existing docs, git state, any planning notes already present]

Agent: Phase 1 complete. Here’s the profile:

Project: recipe app
Size: 2 files — README.md (brief) + planning-notes.md (feature ideas, rough priorities)
Monorepo: no

Docs inventory:
  README.md        ✓ exists (thin — setup instructions only)
  CLAUDE.md        ✗ missing
  PROJECT.md       ✗ missing
  STATUS.md        ✗ missing
  ARCHITECTURE.md  ✗ missing
  docs/            ✗ missing

Existing content: planning-notes.md has goals, a rough user description,
and a list of early features — good seed material for PROJECT.md.

Git state: main, 3 commits.

Agent: Phase 2: Recommendation.

This is effectively greenfield for Michi — a little existing context, no code yet. Recommended scaffold:

CLAUDE.md — build/test commands (stubs for now), conventions, key-file pointers
PROJECT.md — seeded from planning-notes.md (goals, users, early features)
STATUS.md — brief stub: “Pre-scaffold. First epic TBD.”
ARCHITECTURE.md — defer (no code to describe yet). Roadmap.
First epic: docs/epics/recipe-search/ — the planning notes name search as the first priority; I’d scope the epic there
docs/reference/code-style.md — empty stub
docs/reference/docs-refactorings-roadmap.md — tracks deferred items

Two questions before I start:

Docs root: default is docs/. OK?
First epic name: the planning notes call out search first — I’d name it recipe-search. Good, or do you have a different name in mind?

You: docs/ is fine, recipe-search works

Agent: Drafting all the Michi artifacts now.

[the agent creates CLAUDE.md, PROJECT.md, STATUS.md, the first epic directory with a plan stub, journal, verification stub, code-style stub, and the roadmap file — then reports]

Agent: Bootstrap complete.

Created: CLAUDE.md, PROJECT.md, STATUS.md, docs/epics/recipe-search/plans/m1-plan.md, docs/epics/recipe-search/verification/test-plan.md, docs/epics/recipe-search/journal.md, docs/reference/code-style.md, docs/reference/docs-refactorings-roadmap.md, .claude/rules/project-rules.md

Preserved: existing README.md and planning-notes.md untouched. Planning notes are referenced from PROJECT.md; absorb into the relevant epic when one emerges per the roadmap.

Deferred: ARCHITECTURE.md, branching convention — tracked in the roadmap.

Next: /michi-planning to scope the first milestone for recipe-search, or /michi-session if the plan stub is enough to start.

The full guide

You have a project and you want to start using Michi. Before any planning session, before any iteration cycle, you need the doc structure and conventions in place. That’s what bootstrap does.

Bootstrap is not part of the iteration cycle. It is one-time setup that precedes the cycle. The iteration cycle — Explore → Brainstorm → Plan → Execute → Verify → Document — is what you do inside the structure bootstrap creates. Run bootstrap first; run everything else after.

The three-phase flow

Bootstrap is procedural: survey → recommend → execute. Run /michi-bootstrap and the agent walks you through it interactively.

Survey. The agent inventories your project — file count, language, existing docs, git history, any Michi artifacts already present. It is reading, not deciding. Let it finish before directing it anywhere.

Recommend. Based on the survey, the agent proposes an effort tier. For greenfield projects — new or near-empty — that’s a full scaffold from scratch. For brownfield — existing code and docs — it’s a gap analysis with S/M/L/XL options. You pick how much to set up now; everything deferred goes into a docs-refactorings-roadmap.md you can come back to.

Execute. The agent drafts each document with you, not autonomously. It proposes content; you review, steer, and approve. Nothing gets generated and dumped. When execute is done, the project is ready for its first epic.

The bootstrap reference page covers what gets created and what each artifact does. This guide is about how to use bootstrap well — which flavor applies to your situation, what to watch for, what can go wrong.

Flavors

Greenfield

New project, blank slate. Bootstrap creates the full scaffold: CLAUDE.md, PROJECT.md, STATUS.md, the docs/ directory structure, your first epic directory. The agent asks about goals, users, key features, and tech stack as it drafts each doc. Answer what you know; defer what you don’t — the docs can be stubs.

Brownfield

Existing project with code — and often some docs. Bootstrap’s most important job here is the survey: understanding what you already have before proposing anything. Pick the tier that fits your budget:

S — CLAUDE.md with build/test commands and a pointer to existing docs. Minimal, gets Michi unblocked.
M — S plus PROJECT.md and STATUS.md. The common starting point.
L — M plus ARCHITECTURE.md and a first epic directory. Full scaffold.
XL — everything, including converting existing docs to Michi conventions. High effort; rarely warranted right away.

Deferred items go to the roadmap — you haven’t lost them, you’ve staged them.

Multi-project repo

Monorepos and multi-service repos need one additional layer: ROOT/ for the umbrella’s working docs, and docs/<name>/ per sub-project. The umbrella’s identity docs — CLAUDE.md, PROJECT.md, STATUS.md, ARCHITECTURE.md — stay at repo root. The per-sub-project dirs scale independently; each sub-project picks its own tier.

Run /michi-bootstrap at the repo root. The skill handles the ROOT/ idiom and asks how many sub-projects to set up now.

With local customizations

If your project or team has conventions that override Michi’s defaults — commit format, branch naming, code style rules, team-specific workflow steps — run /michi-bootstrap customize after the initial bootstrap. It creates an extensions.md file and wires the @-reference so skills pick it up automatically. Team conventions live in extensions.md’s ## Common section.

Team vs. solo

Solo bootstrap is mostly about doc structure. Team bootstrap adds shared conventions: how STATUS.md works across multiple contributors, what goes in CLAUDE.md vs. extensions.md, commit and PR norms. If multiple people will run Michi sessions on the same codebase, settle these in bootstrap — it’s much harder to converge on them mid-epic.

After bootstrap

Bootstrap ends when the docs exist. Two things to do immediately:

Wire @-references in CLAUDE.md. Point at the first epic’s plan doc once planning creates it:
```
## Current Work
@./docs/epics/my-first-epic/plans/m1-plan.md
```
The @-reference mechanism controls what the agent loads at session start. Without it, the agent opens cold.
Run planning. Bootstrap doesn’t scope your first epic — that’s /michi-planning. Bootstrap just makes planning possible.

See the tutorial to walk through the first planning → execute → debrief cycle.

Pitfalls

Deciding the fix list before presenting the survey. Bootstrap is collaborative — the agent surveys, then presents findings, then the two of you decide what to do. Pre-loading a recommendation before the human sees the survey is the agent getting ahead of itself. If you see this: ask for the survey first, then ask for a recommendation.

Over-scaffolding. ARCHITECTURE.md before the project has architectural shape, or a full epic directory for a greenfield project where you don’t yet know what the first epic is — these create empty shells that immediately drift. Defer to the roadmap. A sparse but honest doc is more useful than a complete but fabricated one.

Filling scope during bootstrap that belongs in planning. Bootstrap creates structure. If you notice the agent starting to plan milestones or write acceptance criteria during the execute phase, stop it — that work belongs in /michi-planning. Bootstrap scaffolds the container; planning fills it.

A worked example

A three-person team has a five-year-old Node.js service with no docs. They want to use Michi for a new authentication migration epic.

They run /michi-bootstrap. The agent surveys: 80 source files, six test files, an old README.md, a package.json, no Michi artifacts. It recommends M-tier — CLAUDE.md, PROJECT.md, and STATUS.md. The team agrees and defers ARCHITECTURE.md (the service has accreted structure; documenting it accurately would warrant its own focused effort).

The agent drafts CLAUDE.md first, asking about build commands, test commands, and existing code style conventions. One team member knows the test command (npm test); another fills in the linting setup. They add a ## Common conventions section noting their branch naming pattern.

Then /michi-bootstrap customize — the team has a commit message format and a PR review convention. These go into extensions.md under ## Common. The @-reference is wired.

Bootstrap ends in one session. The team’s first epic — the authentication migration — is still unscoped. That’s /michi-planning’s job, running the iteration cycle that bootstrap made possible. The first epic is always Paired.