getting-started

Install the command-line tool, write a small plan, and run it. Optional AI skills can draft plans from your notes and carry out the steps for you.

The examples below use a terminal. If command-line tools are new to you, copy each line that begins with $ and run it in order. The $ is the prompt; do not type it.

1 · Install the CLI

# a) global command from a clone
$ git clone https://github.com/leemeichin/marionette && cd marionette
$ npm install && npm link          # installs deps, builds, puts `marionette` on PATH
$ marionette version

# b) zero-clone, from anywhere (npm builds it transparently on first use)
$ npx --yes github:leemeichin/marionette validate plan.mar

Use npm link if you expect to run Marionette often. Use npx if you only want to try it or run it in automated checks.

2 · Write and validate a first plan

Start with a small project. Each named section is a stage of the work, not an individual task. The choices at the end of a stage decide what happens next.

# project: importer
VAR api_attempts = 0

=== build_importer ===
Build the importer against the vendor API.
~ api_attempts += 1
* [API integration works] -> signoff
+ {api_attempts < 3} [Tweak and retry] ~loop~ -> build_importer
* {api_attempts >= 3} [API not viable] -> csv_fallback

=== csv_fallback ===
Fall back to CSV upload: same importer surface, manual ingestion.
* [Fallback works] -> signoff

=== signoff ===
Sam reviews the shipped surface.
* [Sam approves, ship it] @human -> END
+ [Changes requested] @human ~loop~ -> build_importer

$ marionette validate plan.mar --strict   # check for problems
$ marionette summarize plan.mar           # read a plain-language summary
$ marionette render plan.mar              # create a flowchart

If validation fails, every diagnostic carries a line number and a help: suggestion — see the walkthrough for what that looks like, and the diagnostic table for the full list.

3 · Optional: use Marionette with an AI assistant

You do not have to learn the plan syntax. The authoring skill turns ordinary notes into a checked draft. The execution skill helps an AI assistant work through the finished plan, record decisions, and stop when a person is needed. In a Claude Code session, install both with:

/plugin marketplace add leemeichin/marionette
/plugin install marionette@marionette

Then give the authoring skill real notes, e.g.:

Use marionette-authoring. Plan this for me: we're migrating the billing
service off Stripe Classic. Spike the new API first — if metered billing
isn't supported we stay put. Up to two spike attempts. Finance signs off
before any customer is switched, and we roll back if error rates spike.

The skill creates the .mar file, checks it, fixes any problems, and shows you a flowchart and summary. It clearly marks every decision that needs a person. For other ways to install the skills, see the full installation guide.

4 · Start and follow the plan

$ marionette state init plan.mar        # start a run and create the progress file
$ marionette brief plan.mar             # show the agent's next assignment
$ marionette state show plan.mar        # show current progress and available choices
$ marionette state choose plan.mar 1 --actor agent --rationale "why"
$ marionette state advance plan.mar --actor agent   # move to the next stage
$ marionette state rebind plan.mar      # accept a plan edit and keep the history
$ marionette render plan.mar            # show progress on the flowchart

Marionette applies three important rules. An agent cannot take a choice marked @human. Every choice needs a written reason. If the plan changes after the run starts, Marionette stops until you accept the edit with state rebind. To let an AI assistant handle this process, use the execution skill. See the execution guide for details.

5 · Keep it honest in CI

You can run Marionette in automated checks. A successful command returns 0; problems return a different number so the check can stop. This minimal setup checks plans for errors and notices if a running plan has been edited:

$ marionette validate plans/*.mar --strict     # plans stay sound
$ marionette state show plans/project.mar      # exit 3 = plan edited without rebind