What is Michi?

Michi is a toolkit for AI-assisted software development. It embodies an approach — the way — for cultivating judgment in the practitioner and the agent, with autonomy earned rather than assumed.

The name is Japanese: 道 (michi), “the way.” The kanji is the same one that appears in martial and traditional arts — kendō, judō, chadō — where “-dō” names the practiced path, the disciplined way of doing a thing. A playbook you internalize until it becomes how you work.

The ideas behind it

Michi grew out of a few convictions. The first: understand the problem before jumping to solutions. It’s easy — especially when working with an agent that can write code in seconds — to skip straight to implementation. But an elegant solution to the wrong problem is waste. Requirements and reasons first, implementation second.

The second: speed without sustainability is a trap. Fast iterations matter — shrink the distance between “what if” and “here’s what happened” — but each iteration should leave the system where the next one is at least as productive. Code health, test health, knowledge retention — these aren’t chores you schedule when things calm down. Things never calm down.

And the third: match your process to the size of the work. A bug fix doesn’t need the same rigor as a multi-milestone epic. Rate the effort against the benefit, the risk against your readiness, and apply the right amount of structure. Not every problem is large, and not every solution needs to be.

These ideas are developed fully in Principles. They’re the reason Michi exists as a separate toolkit rather than just a set of CLAUDE.md rules. Rules tell the agent what to do. Principles tell you how to think about the work — and when to break the rules.

What Michi provides

Three things:

Process. An iteration cycle — Explore → Plan → Execute → Verify → Document — that applies at every scale, from a single milestone to an entire epic. Each iteration produces both working software and richer context for the next iteration. Spirals, not circles.

Skills. Nine Claude Code slash commands covering the full development lifecycle: bootstrap a project, plan a milestone, execute with verification discipline, debrief, assess sustainability. Each skill encodes the questions and discipline that make agent work reliable.

Structure. A documentation approach — plan docs, verification scenarios, journals, decision logs — that survives context compaction and compounds knowledge across sessions. The agent writes to it during implementation; you review it during debrief.

Looking for something light or quick? There is the Workshop.

Paired and Entrusted

Michi has two operating modes.

Paired is human and agent thinking together — exploring, calibrating, working through problems with both eyes on. It’s the default, especially for new territory.

Entrusted is wider autonomy within established scope. The agent working inside verification infrastructure; the human reviewing at gates rather than steering every move. It’s earned through demonstrated mastery of the tools, the codebase, and the verification discipline.

A metaphor that helps: Paired is lights-on — you see the agent’s work directly. Entrusted is lights-off — verification infrastructure, decision logs, and scenario discipline see for you. The project is about earning the right to turn the lights off. And knowing when to turn them back on.

Who this is for

Engineers using Claude Code for sustained, multi-milestone development — not one-off tasks. If you’ve tried agent coding and found it powerful but inconsistent, this is the structure that closes the gap.

You should be comfortable with CLI tools, git, and markdown. You’ve used AI coding assistants for real work. You may or may not have a structured process for it. You’re looking for practical guidance, not theory.

A few things to keep in mind

This is what works for me. I’m sharing it because I think the ideas are useful, not because I think everyone should adopt it wholesale. Your context, skills, and codebase are different from mine — what I have to offer might not apply.

Before building Michi, I used Jesse Vincent’s superpowers plugin, and I’d still recommend it. It’s well-designed, battle-tested, and may be everything you need. Michi grew out of wanting something more opinionated about verification and documentation, but superpowers is a great starting point.

Michi is pre-1.0 and evolving. The principles are solid — they’ve survived multiple real projects. The tooling is still being refined. I’ll be honest about what’s unsolved.

How I got here

I first read about a software dark factory in StrongDM’s post. What struck me wasn’t the imagery of autonomous agents running without supervision — it was that a small team, not a platform org with dedicated tooling, had done it. That made it feel tractable for a solo practitioner.

So I experimented. A real project — a JavaScript monorepo, nine planned milestones, a dedicated machine, and an agent with a spec and a plan. Three sessions. ~80 files. 221 tests. Zero test failures at completion.

And two bugs that escaped to post-completion — both caught by a human running the code for real, not by any test the agent wrote. Those two bugs are why Michi exists. They revealed a systemic problem that more tests can’t solve: the agent grades its own homework. Tests pass ≠ work is done. Read more about what went wrong →

Two insights shaped what the toolkit became as I iterated on it:

1. It’s not just about autonomy. Sometimes you work paired because you need to explore with a partner. Sometimes you work entrusted because rapport and discipline let you step back. The paired/entrusted distinction fit lights-on/lights-off; it still does.

2. It’s not harness engineering. I wasn’t chasing better rails. I was chasing agent judgment — and my own, alongside it. Once that was named, the way turned out to be the right organizing image. The factory metaphor stayed where it earns its place: explaining how modes work, narrating where the toolkit came from.

For the longer version — the first experiment in detail, the agent-grades-its-own-homework moment, the toolkit building itself, the things that are still open — see The Story.