moplan

Moplan

CRISPI structured planning for AI-assisted development. A Claude Code plugin that turns freeform plan mode into reviewable YAML plans with vertical slices, dual-agent critique, and an interactive marimo review notebook — all local, all yours.

Install

Add the marketplace, then install the plugin:

/plugin marketplace add shakestzd/moplan
/plugin install moplan

Both commands run inside a Claude Code session. Moplan only requires uv to be on your PATH (the marimo notebook uses uv run --script to create an isolated Python environment on first run — no global pip install, no virtual-env setup).

If you prefer to run from a local checkout:

/plugin marketplace add /absolute/path/to/moplan
/plugin install moplan

What is CRISPI?

CRISPI is a structured planning format for software work. Every plan has the same five sections so humans and agents can read it the same way:

Section	What goes here
C — Context	Current state, evidence, what is wrong, why it matters now
R — Requirements	Measurable goals and hard constraints — what "done" looks like
I — Implementation	Vertical slices with what, why, files, done_when, tests, effort, risk, deps
S — Scrutiny	Dual-agent critique — a design critic challenges assumptions; a feasibility reviewer verifies claims against the real code
PI — Progress Items	Open design questions with recommended answers, approval state, chat amendments, finalize status

Plans are YAML files (.moplan/plans/plan-<id>.yaml) so they are hand-editable, diffable, mergeable, and greppable. Approval state is SQLite (.moplan/moplan.db) so clicks in the review notebook are atomic and survive restarts. That split is deliberate — content as text, state as rows.

Running moplan

Create or reopen a plan

/plan                       # opens the picker (pick an existing plan or create a new one)
/plan plan-9ae3f59b         # reopens a specific plan by id
/plan path/to/plan.yaml     # loads a plan from an explicit path

Under the hood, /plan runs:

cd ${CLAUDE_PLUGIN_ROOT}/notebooks && uv run --script plan_notebook.py -- --plan "$ARGUMENTS"

uv run --script reads the PEP 723 header inside plan_notebook.py and installs the required Python packages (marimo, pyyaml, anywidget, traitlets, anthropic) into an isolated environment on first run. Subsequent runs reuse the cache.

Review flow

The marimo notebook surfaces every part of the plan for human review:

1. Design Discussion — problem, goals, constraints. Approve the design section or leave a comment.
2. Slice cards — one per vertical slice. Click to expand; approve each one individually.
3. Open Questions — each question pre-selects the agent's recommended option. The reviewer overrides only where they disagree.
4. AI Critique — dual-agent findings (design critic + feasibility reviewer), rendered as assumption badges, risks, gaps, alternatives, and prior art.
5. Chat sidebar — a Claude-backed chat pane that can emit AMEND slice-N: ... directives. Accepted amendments are applied to the YAML when you finalize.
6. Feedback Summary — progress bar.
7. Finalize — click when every section is approved. The plan YAML is rewritten with the approved state and a static HTML archive is exported alongside it.

Every click persists to .moplan/moplan.db immediately, so you can close and reopen the notebook without losing progress. The store is discovered by walking up from your current directory until .moplan/ or a git root is found; if neither exists, it bootstraps .moplan/ at the git root and logs that action to stderr — never a silent no-op.

The deliverable

The finalized plan YAML is the output. Moplan does not ship an executor and does not create work-tracker entries on your behalf — the point is a structured, reviewed plan you can hand to any workflow (manual implementation, /htmlgraph:execute, GitHub issues, your own scripts). If you want to execute the slices with HtmlGraph's parallel dispatch, install that plugin separately and point /htmlgraph:execute at .moplan/plans/plan-<id>.yaml. If you don't, just read the file.

Project layout