michi-session
The session skill executes an implementation milestone. It is the most rigid skill in the toolkit — every step is mandatory, every verification is required, every decision is logged. The discipline is the point. This is where code gets written, tests get run, and milestones get delivered.
When to use
Section titled “When to use”- Implementing a milestone that has a plan doc from
/michi-planning - Any implementation work that requires the full Michi discipline — verification, decision logging, sustainability checks
- Both code milestones (features, APIs, bug fixes) and non-code milestones (research deliverables, design documents)
What it does
Section titled “What it does”Pre-flight. The agent reads the plan doc (the implementation contract), verifies the correct git branch, checks the environment (services running, tests passing from clean state), and loads project conventions from CLAUDE.md. It also scans the plan’s steps for commodity needs an existing dependency or open-source library could cover, and notes the candidates in the plan doc before work starts. If no plan doc exists, it stops and directs you to /michi-planning first.
Core loop. The agent executes the plan’s steps using the target-appropriate loop. For code, TDD is the default: write a failing test, implement, pass, refactor, repeat. It skips TDD only when you say so for a given milestone (“skip TDD for this one”), typically for spikes, prototypes, or mechanical refactors already pinned by tests. For non-code: Explore, Synthesize, Checkpoint. Throughout, it logs every decision immediately — classified as implementation-detail (internal, no notification), design-choice (human reviews during debrief), or contract-change (a change to behavior or a contract that users, callers or other projects already rely on; notify human immediately). Discussion items — things the agent can’t decide alone but isn’t blocked on — are logged separately.
The Iron Law: no “done” without running full verification. After all steps are complete, the agent runs the full verification checklist. “I believe it passes” is explicitly forbidden — the agent must run the commands, read the output, and report actual results. For code targets this means self-review, scenario execution, and code review. For non-code targets, self-review against exit criteria.
Sustainability check. Before the commit hand-off, the agent runs a sustainability pass: refactoring opportunities, test evaluation, scope check, and any emerging discussion items.
Ready to commit and post-milestone. The agent does not commit. It hands off to you with a proposed commit message prefixed michi(mN):, and you run the commit. It updates the plan doc with completed steps and deviations, updates STATUS.md, and notifies through the established channel.
What it produces
Section titled “What it produces”- Implemented milestone — working code with tests, or completed non-code deliverables
- Updated plan doc — steps checked off, decisions logged, notes captured, discussion items recorded
- Proposed commit message prefixed with
michi(mN):, with a summary of what was built and key decisions, for you to commit - Updated STATUS.md reflecting current project state
- Memory updates to
docs/memory.mdif warranted — collaboration patterns that would be painful to lose
Key things to know
Section titled “Key things to know”- This skill has an explicit list of “red flags” — rationalizations that trigger a stop. “This decision is too minor to log,” “Tests passed during implementation, verification is redundant,” “I’ll update the plan doc later” — the agent is instructed to catch these thoughts and override them.
- Reactive scope changes are handled differently by mode. In Paired mode (human present), scope can expand when a spike confirms feasibility and the human agrees. In Entrusted mode, prefer creating a new milestone over expanding the current one.
- Scope you add mid-session (“while we’re at it, also do X”) is absorbed without ceremony when it fits after the current work. Only additions that reshape planned milestones get surfaced and confirmed before the agent proceeds.
- If the epic has a
north-stars.md, the agent re-reads it at a reactive scope change, at any “simpler”, “interim” or “for now” proposal, and before claiming the milestone done, and writes a line in the plan doc naming which north star the step serves or trades. A trade becomes a## Discussionitem for you, never a decision the agent makes. - The plan doc is the report; chat is the summary. Progress detail goes to the plan doc, and each chat turn is short: what changed, anything surprising, what’s next, any question. If you ask for less narration, the narration shrinks but the verification does not.
- The Rule of 3 applies: three rounds without progress on the same problem means stop, reframe, and escalate — not try a fourth time.
- When genuinely blocked, the agent documents the blocker in the plan doc, notifies you, and waits rather than working around it. If an Entrusted session has stalled, look there first.
- The natural next step after a session is
/michi-debrief, either immediately or in a separate session.
For the full agent instructions, see the SKILL.md source.