Skip to content
Michi v2026.11.16
Save the Tokens

michi-bootstrap

The bootstrap skill onboards a project to Michi’s documentation structure. It surveys what already exists, identifies gaps against the Michi standard, and walks you through setup interactively. This is the first skill you run on any project — before planning, before sessions, before anything else. It works for brand-new projects (greenfield) and existing codebases being prepared for Michi work (brownfield).

  • Setting up a new project for Michi work
  • Onboarding an existing codebase that has never used Michi
  • Re-running on a project with partial Michi structure to close remaining gaps
  • When you’re unsure what Michi docs a project already has versus what it needs

Run /michi-bootstrap for the default onboarding. It runs three phases, with human checkpoints between each.

Survey. The agent scans the codebase for size, language breakdown, and structure. On a large monorepo it first shows the top-level structure and asks which parts to focus on and which directories to exclude; the rest of the survey covers only that scope. If the repo looks like it holds sub-projects with their own dev lifecycles, the agent asks whether to set up the multi-project layout: docs/ROOT/ for the umbrella project’s work and docs/<name>/ for each sub-project. It inventories existing documentation — README, CLAUDE.md, PROJECT.md, STATUS.md, ARCHITECTURE.md, any docs directories — and assesses each file as substantive, stub, stale, or missing. It checks whether docs/ already contains non-Michi content (product docs, API docs) and asks where Michi docs should live. The result is a structured project profile presented for your review.

Recommend. For an existing project, the agent presents effort tiers. Each tier is additive — S (essentials: CLAUDE.md and STATUS.md), M (foundation: adds PROJECT.md and first epic directory), L (full setup: adds ARCHITECTURE.md, reorganizes existing docs), XL (deep onboard: adds verification infrastructure, scenario catalog, code-style stub). You pick a tier, mix across tiers, or cherry-pick. Anything deferred goes to a refactoring roadmap. For a brand-new project (no existing docs, little or no code), the agent skips tier selection and, once you confirm, scaffolds the full Michi structure. In a multi-project repo, the umbrella and each sub-project get their own tier, and a sub-project with nothing yet can be skipped.

Execute. For each artifact in scope, the agent drafts content based on survey findings, presents it for review, and writes the file after approval. Nothing is generated and dumped silently — every artifact is a mini-collaboration.

Three other modes do narrower jobs:

  • /michi-bootstrap customize creates docs/reference/extensions.md, a file of project- or team-specific overrides that every Michi skill checks before applying its defaults; anything in it takes priority. The agent adds @docs/reference/extensions.md to CLAUDE.md so it loads at every session start. If the file already exists, the agent asks whether to review or edit it, and never overwrites it.
  • /michi-bootstrap multi-project migrates a single-project Michi repo to the multi-project layout. After you approve a preview, it moves docs/epics/, docs/reference/, docs/journal.md and docs/memory.md under docs/ROOT/ with git mv (one move at a time, so history is kept), adds the project index and multi-project: true to the repo-root CLAUDE.md, and creates docs/<name>/ for each sub-project you name. The root docs (CLAUDE.md, PROJECT.md, STATUS.md, ARCHITECTURE.md, README.md) stay where they are.
  • /michi-bootstrap expedition [name] sets up the root that /michi-expedition works from: STATUS.md, iteration-log.md, backlog.yaml, ruminations.md, and empty charters/, portraits/, campaigns/ and reference/ directories, at expeditions/ or docs/epics/<name>/. With you, it records how to access the material being explored in reference/, then hands off to /michi-expedition charter. Run this before your first expedition.
  • CLAUDE.md with build/test commands, conventions, and @-references to other docs
  • STATUS.md reflecting current project state
  • PROJECT.md with goals, users, and features (M tier and above)
  • First epic directory with verification and plans subdirectories (M tier and above)
  • ARCHITECTURE.md with design overview (L tier and above)
  • docs/reference/code-style.md stub for applied coding principles (XL tier, and always on a brand-new project). On a brand-new project the agent also creates .claude/rules/project-rules.md with an @ reference so the stub loads automatically.
  • docs/reference/docs-refactorings-roadmap.md, written on almost every existing-project run. It lists anything deferred, with rationale, and suggests a branching convention if git history shows none.
  • This is a collaborative, interactive skill — the agent drafts, you review, then it writes. It does not run autonomously.
  • For brownfield projects, the agent shows proposed moves and merges before acting. It won’t silently reorganize existing docs.
  • If docs/ already has non-Michi content, the agent will ask where to put Michi docs and record the decision as docs-root in CLAUDE.md.
  • The natural next step after bootstrap is /michi-planning to prepare the first milestone, or /michi-explore if the project needs more investigation first.

For the full agent instructions, see the SKILL.md source.