Open Steps

Skills that keep development open to the person running it: the sessions, the decisions, the next steps, all in plain language.

By Pavlo Kharmanskyi.

I'm not an engineer. I'm a market-led builder: I look for where demand already exists and the infrastructure doesn't, then build the missing piece. Twenty years of building web and software products, always from the product side, and more than 50 developers at my company today.

Apart from the company, I started building a product on my own, just vibecoding. Partly to stay ahead of where all this is going, partly because I think the moment has arrived for people like me: you can now imagine a serious product and build it yourself, with no engineers or very few of them.

Then I ran straight into a wall. The agent does excellent work, then tells me about it in commit hashes and jargon, and I genuinely cannot tell whether we are done. Not because the work is unclear. Because nobody taught the agent to talk to someone who doesn't speak engineering.

So I built this pack. I'm sharing it here for anyone in the same position, and that's the whole idea behind the name: every step of building with an agent, kept open to the person doing the building. Right now it changes what the agent tells you. Where I want to take it next is the work itself, not just the reporting.

Before and after

The whole idea in one screen. Work ends, you ask "are we done?".

Without the pack:

Hotfix deployed: session TTL misconfig in auth middleware caused 401 cascades after key rotation; patched the refresh path, invalidated stale JWTs, redeployed api+web. p95 back to 180ms. Root cause: env drift after the 09-14 rollout. Two flaky e2e specs quarantined (known, tracked)…

With it you get this:

People can sign in again. A bug was logging people out because their sessions expired far too early. The fix is live for everyone.

✅	Response times are back to normal
⚠️	Until this shipped, people were being logged out over and over.

Fully done?	Yes
Anything needed from you?	No
New debt?	Two small ones, written down
Safe to close?	Yes

Same facts. One screen. The bad news gets its own row instead of hiding in the middle of a paragraph. A second, longer example from a real session lives in this repository, with notes on what the rewrite changed: skills/os-done-or-not/references/01-prod-promote.md.

Quick start

Claude Code is what the pack is built and measured on, and the only tool where everything works with no extra steps. The skills and the routing block also install into Codex, Cursor and Gemini CLI, see Other agents below. git and gh are optional: a couple of the skills read project state through them, and without those tools more of the output honestly says "not checked".

Clone this repository:

git clone https://github.com/kharmanskyi/open-steps.git

Both commands below run from the folder you cloned it into, the one that now holds open-steps/, not from inside the clone. First, install it as a plugin:

claude plugin marketplace add ./open-steps && claude plugin install open-steps@open-steps

That's it. The skills and both hooks are wired for you. Check what you got:

claude plugin details open-steps

One thing is worth adding by hand, and no installer can do it for you: a short block in your own ~/.claude/CLAUDE.md. Skills are something the model chooses to use. The hooks remind it; the block makes it a rule, and it survives long conversations. One command, from the same folder, safe to re-run:

grep -q 'os-done-or-not' ~/.claude/CLAUDE.md 2>/dev/null || cat open-steps/docs/routing-block.md >> ~/.claude/CLAUDE.md

The reasoning is in docs/claude-md.md.

To update: claude plugin update open-steps. To remove: claude plugin uninstall open-steps, then take the block back out of your CLAUDE.md.

The one piece that stays manual is the writing style, because turning it on would silently replace whatever style you already chose. Two lines, in docs/output-style.md.

Other agents: Codex, Cursor, Gemini CLI

Codex, Cursor and Gemini CLI all read ~/.agents/skills/, so one command installs the pack into all three. Run it from the folder holding the clone:

mkdir -p ~/.agents/skills && cp -R open-steps/skills/os-* ~/.agents/skills/

Then the routing block goes into whatever that tool treats as your standing instructions, doing the same job it does in CLAUDE.md above:

The hooks are the part that differs per tool. Codex runs both of them unchanged, with a short block in ~/.codex/config.toml and one trust prompt to accept. Cursor and Gemini CLI want JSON where these two print text, so both need an adapter that is not written yet, and on Cursor a stop cannot be blocked at all. On both, the skills and the routing block install; how reliably the skills fire there is not checked.

The commands, the paths, the Codex hook config, and what was run rather than read: docs/other-agents.md.

The skills

They work as a loop: os-whats-next picks the work, os-step-by-step walks you through your part, os-done-or-not reports the result, os-check-work accepts what other sessions did, os-ask-simple handles the questions on the way, and os-say-simple rescues any text that still reads like engineering.

Numbers

The pack tells the agent to separate what it measured from what it assumed. Same rule for me.

Eighteen phrases a person would actually say, three of them per skill, each asked three times, headless, in a working installation, on three Claude models. The question every time: did the right skill switch on by itself? Three off-topic questions, each also asked three times, checked the opposite.

The honest reading, because the misses matter more than the score.

• On Sonnet 5 and Opus 5 this works. Three skills are perfect on every model.
• On Haiku 4.5, two skills are unreliable and one off-topic question wrongly pulled in a skill. If you run on the cheapest model, expect to type the skill name yourself sometimes.
• Haiku also moves between runs. An earlier sweep of the same phrases put os-step-by-step at 50% where this one puts it at 33%, and put false fires at zero. Three runs per phrase is a smoke test, not a benchmark, and small numbers wobble. I would rather say that than quote the friendlier sweep.
• Where Haiku misses, it usually asks a clarifying question first: told "put a secret on the server, tell me what to do", it wants to know which server and which secret. That is the pack's own earn-the-ask rule; a one-shot test scores it as a miss.
• The test set is mine, and it is small. Eighteen phrases in a repository you can read, so write better ones and re-run it.

Two things earlier rounds cost me, kept here because they are the useful part. A negation inside a description ("this is NOT the skill for X") is ignored, so boundaries between overlapping skills get drawn by removing triggers, not by adding warnings. And a phrase with a false premise ("you said X" at the start of an empty session) is refused by the model, correctly, so test phrases have to carry their own context.

Everything is in evals/, and two files are enough if you just want to look: cases.md is every phrase we ask, [results.md](evals/r