stepchain

Sequential step-chains for structured, resumable multi-step work in Claude Code.

A step-chain is the plan of a non-trivial task as a machine-readable truth on disk: a goal, numbered steps, an advancement condition per step, and a single active-step pointer. The pointer is remanent — it survives a crash, a token limit, a closed session — so the work always knows which step it stands at. Advancement is gated on proof (a step only moves forward when a real command passes), and a broken chain fails loud instead of silently drifting into a wrong state.

It is the SFC / Sequential Function Chart principle from IEC 61131-3 industrial control (the way a PLC runs a step sequence), applied to how an AI agent structures multi-step work. The engine is deterministic — no LLM inside.

---

Why this exists

stepchain grew out of a specific, honest problem, in four layers:

1. The trigger — an AI acting without a relevance gate. The failure of an AI agent on a long task is rarely noticing a problem; it is acting on it without a gate in between. A cosmetic irregularity gets "fixed" into a sprawling detour; a plan gets lost halfway when the context resets. stepchain began as a guardrail against exactly that: a discipline that forces a defined goal, a fixed path, and one step at a time.

2. The model — a step-sequence controller. The remedy came from industrial automation: work like an SFC / PLC step sequence. A defined goal, ordered steps, an advancement condition on each, and always exactly one active step. Discover a problem → it goes into one of two lanes (note it and carry on, or emergency-stop), never a silent inline detour.

3. The core insight — remanence. An agent's context is volatile memory. A crash or a token limit must never blur which step the work is on. So the step-pointer lives on disk — like the step latch in a PLC's battery-backed memory that holds the step across a power failure. The machine-readable chain file is the truth, not the agent's memory.

4. Why share it. The "AI operating system for Claude Code" space is crowded, but the one piece that kept being absent from the neighbours was this: the SFC/PLC discipline packaged as a remanent, gated, resumable state machine for the agent. That is what stepchain is.

(The name is the German industrial term "Schrittkette" — a step-chain — carried over from where this was first built.)

---

The real user is the agent, not you

You don't author a "staged project" that then runs through stepchain. You work normally. When you hand Claude a large, multi-step task ("build this feature in stages", "migrate the database", "refactor across these files"), Claude — guided by the bundled skill — slices that task into a chain on the spot, works one step at a time, and advances only when each step's proof passes.

If the session dies, the next one immediately sees Step 3/6 active: implement X — condition: tests green and resumes there instead of losing the plan.

Honest scope — capability, not enforcement. This plugin gives you the mechanism (the chain, the gate, the remanent pointer, the auto-resume lamp) and the instructions for the agent to use it. It does not force the agent to use it — a shareable plugin cannot wire enforcement deep into your project without overreaching. Reaching for the chain is driven by the skill's description (and, optionally, a line in your own CLAUDE.md). If you want it to be near-automatic, see the two-liner below.

---

Getting started — how a project becomes a stepchain project

1. Install the plugin (see Install below). Immediately available, with no configuration: the stepchain skill (Claude now knows the capability), a SessionStart hook (the auto-resume lamp), and the CLI.

2. Start a chain. The first time Claude (or you) creates a chain, a .stepchain/ folder appears in your project — that is the activation moment. Everything about the chain lives there, in your project, not in the plugin folder.

   # Claude Code sets CLAUDE_PLUGIN_ROOT for you; on any other host point PYTHONPATH at the
   # directory that contains the stepchain/ package (i.e. the unpacked skills/ folder).
   export PYTHONPATH="${CLAUDE_PLUGIN_ROOT}/skills"
   python -m stepchain new "Ship feature X" --goal "X live and verified" \
     --step "Design|design review passed" \
     --step "Implement|unit tests green|pytest -q" \
     --step "Deploy|smoke test green|./scripts/smoke.sh" \
     --active

3. It carries itself. Every session start prints the open step (the lamp). After a step's proof is green, step-done advances the remanent pointer before you commit, so the progress is saved with the work.

   python -m stepchain show        # where are we?
   python -m stepchain step-done   # gated advance: run the step's proof, move only if green
   python -m stepchain list        # all chains + state (foreground / dormant / done / halted)

Optional: make Claude reach for it consistently

Add a line to your own project's CLAUDE.md:

For any non-trivial, multi-step task, track it as a stepchain: create a chain with ordered steps and advancement conditions, work one step at a time, and advance only on a green proof.

What makes a good step

The value of a chain is only as good as the slice. A well-formed step is verifiable (ideally a runnable proof — if you can't say how you'd check it, it isn't a step yet), one concern, ordered, a safe checkpoint, and non-trivial. That runnable gate on every step is what makes a step-chain more than a to-do list.

---

Commands

Verb	What it does
new	create a chain (--step "Title|condition|proof command", repeatable — the proof is optional; --active to bring it to the foreground)
show	show the active chain and its lamp
advance	advance one step (ungated)
step-done	gated advance: run the active step's proof, advance only on exit 0 (fail-loud on non-zero)
check	run the active step's proof and report, without advancing
halt "reason"	emergency-stop lock (only a human releases it)
release	release the halt
list	all chains + derived state
switch <path>	bring another chain to the foreground (the previous one rests)
rest	clear the foreground (all chains rest)
validate	load + validate a chain file (fail-loud)
lint	report structurally weak steps (no advancement condition / no runnable proof); advisory, never gates

Every command prints a JSON object; exit 0 on success, 1 on error. Full contract and the chain-file schema are documented in the bundled skill (skills/stepchain/SKILL.md).

---

Trust & security

A step's proof is an executable command, run with your own privileges (as an argv list — no shell is involved, so there is no shell-injection surface). check and step-done are the only commands that run it; nothing runs automatically — in particular the SessionStart hook only reads chains to print the lamp, it never runs a proof.

Because the proof lives inside the chain file, treat a chain file as code, not just data:

• Only run check / step-done on chains you trust.
• Be careful with a .stepchain/ (or projects/*/stepchain.json) that arrives inside a cloned or third-party repository — its proof commands would run on your machine when advanced. Read the proof (stepchain show prints it) before running an unfamiliar one.

Everything runs locally; the plugin makes no network calls and collects no data (see PRIVACY.md).

---

Install

Requirements: Python 3 available on PATH (the engine is Python; no third-party packages).

• Try it locally (no publishing, no commitment):

  claude --plugin-dir /path/to/stepchain

• From a marketplace: once the plugin is in a Claude Code plugin marketplace, add the marketplace and install stepchain from it.

State (chain files + the foreground pointer) is written to ${CLAUDE_PROJECT_DIR}/.stepchain/ by default, or to $STEPCHAIN_HOME if you set it — never inside the plugin folder, which is wiped on plugin updates.

---

License

MIT © 2026 Bernd Zips. See LICENSE.