Open Steps: plain-language reports for coding agents

The wall Open Steps was built to knock down

The project comes from a single complaint. Its author, Pavlo Kharmanskyi, describes himself in the README as "not an engineer" and a market-led builder, and says he hit a wall while vibecoding a product on his own: the agent does good work, then reports it in commit hashes and jargon, and he cannot tell whether the work is finished. The README frames the problem as a communication gap rather than a code gap. The agent was never taught to talk to someone who does not speak engineering.

So the pack targets the reporting layer, not the coding layer. The README is explicit that this is the current scope: "Right now it changes what the agent tells you. Where I want to take it next is the work itself, not just the reporting." That is a narrow, honest claim, and it sets expectations correctly. Open Steps does not make an agent write better code. It changes the sentence the agent produces when the session ends.

The intended reader is the person running the agent: a solo builder, a product-side founder, a non-engineering stakeholder who is paying for the session and needs to know if it is safe to close. The repository's own before-and-after example makes the audience concrete. A raw report about a session TTL misconfiguration in auth middleware, 401 cascades, stale JWTs and quarantined e2e specs becomes four short lines saying people can sign in again, a bug was logging them out, the fix is live, and yes it is safe to close.

What the pack actually contains: skills, hooks and a routing block

Three mechanisms do the work, and they have different strengths.

The first is skills, which live under skills/os-* in the repository. A skill is something the model chooses to use, which means it is a suggestion, not a guarantee. The README says the pack ships skills and both hooks when installed as a plugin, and that the skills also install into Codex, Cursor and Gemini CLI through ~/.agents/skills/.

The second is hooks. These are the enforcement layer, and the README is candid about how far enforcement goes per tool. In Claude Code both hooks are wired by the installer. In Codex both run unchanged with a short block in ~/.codex/config.toml and one trust prompt. Cursor runs both through hooks/adapter.sh, but a stop cannot be blocked there, so the report is asked for as a follow-up message instead of being required, and only in an interactive session, because a headless run never reaches the stop hook. Gemini CLI also uses the adapter, and there the stop can refuse on AfterAgent. One Gemini-specific constraint is stated plainly: its file tool cannot write outside the workspace, so the request tells the agent to save the report with the shell tool.

The third is the routing block in ~/.claude/CLAUDE.md. The README explains why it exists: skills are optional for the model, hooks remind it, and the block turns the behaviour into a rule that survives long conversations. This is the piece no installer can add for you, and it is the piece most likely to be skipped.

There is also a deliberate omission. The writing style stays manual, because the README says turning it on would silently replace whatever style you already chose. Two lines in docs/output-style.md enable it.

Installing Open Steps as a Claude Code plugin

Claude Code is the tool the pack is built and measured on, and the only one where the README says everything works with no extra steps. git and gh are optional: a couple of skills read project state through them, and without those tools more of the output honestly says "not checked".

Start by cloning the repository.

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

Both install commands run from the folder you cloned into, the one that now holds open-steps/, not from inside the clone.

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

The README states this installs the skills and both hooks. To see what landed, ask the plugin manager for details.

claude plugin details open-steps

For a fuller answer, run the install check inside the agent. According to the README it reports what is wired and what is not, and says "not checked" where it could not look.

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

That last command appends the routing block to your own CLAUDE.md. It is safe to re-run, because the grep guard skips the append when the marker is already present. The reasoning behind it is in docs/claude-md.md. The first real use is simply finishing a session and asking whether you are done: the pack's stated goal is that the answer arrives as a short report with a verdict rather than a wall of engineering detail.

Updating is two steps, and only one of them is obvious

The update path has a trap that the README spells out. You pull inside the clone, then you update the installed plugin.

git pull
claude plugin update open-steps@open-steps

Both halves matter. The plugin updates from your local clone, not from GitHub, so without the pull the message "already at the latest version" is true of the folder on your disk and wrong about the repository. The naming is also asymmetric: update wants the full plugin@marketplace name, while uninstall accepts the short one.

The stricter constraint is that the update moves files only when the version number changed. A pull that brings no new version brings nothing to the installed copy. The practical consequence is a release discipline the project has adopted: every change meant to reach an installed copy ships with a version bump and a release. The recent release history is consistent with that, with v0.4.1, v0.4.2 and v0.4.3 appearing within a few days of each other in September 2026.

Removal is the reverse. Run claude plugin uninstall open-steps, then take the routing block back out of your CLAUDE.md by hand. The README does not document an automated rollback for the block, so that edit is yours to make.

Where Open Steps gets in the way

The clearest limitation is the one the project states itself: skills are something the model chooses to use. Without the routing block in CLAUDE.md, the behaviour is a suggestion that can be ignored, and long conversations are exactly where suggestions decay. If you install the plugin and skip the block, you have installed the weaker half.

The second limitation is tool coverage, and it is uneven by design rather than by accident. The README gives a table of where the routing block goes for Codex, Cursor and Gemini CLI, and notes that the hooks differ per tool. On Cursor the stop cannot be blocked, so the report is requested as a follow-up message rather than required, and only in an interactive session. A headless Cursor run never reaches the stop hook at all. If your workflow is mostly headless, the enforcement story is thinner than the feature list suggests.

The third is the optional dependency on git and gh. Without them, a couple of skills cannot read project state, and the output says "not checked" more often. That is honest behaviour, but it means the report quality depends on tools you may not have installed.

And the scope boundary is real. Open Steps changes reporting, not engineering. If your problem is that the agent produces bad code, this pack does not address it. The README says the next direction is the work itself, which is a statement about where the project is not yet.

The alternative: writing the instruction yourself

The obvious alternative is not another skill pack. It is a paragraph in your own CLAUDE.md or AGENTS.md telling the agent how to report, plus whatever output style you already use. That approach costs nothing to install and has no update path to maintain.

The difference in approach is what you get for the maintenance. A hand-written instruction is one prompt that you own and can change in a line. Open Steps is a versioned pack with skills, two hooks, a routing block, an install check and a release process, and it accepts that the plugin updates from your clone rather than from GitHub. You are trading a small amount of ongoing discipline, the pull-then-update pair and the version-bump rule, for a tested set of behaviours and per-tool hook adapters that you would otherwise write yourself.

Which is better depends on how much of the reporting problem you have already solved. If a single paragraph in your standing instructions already gets you plain-language summaries, the pack adds a dependency without adding much. If you have never got the agent to report usefully, the pack encodes a specific format: a short narrative, a table of good and bad news, and explicit rows for whether the work is fully done, whether anything is needed from you, whether new debt was created, and whether it is safe to close. That format is the actual product.

Licence, maintenance and what to check before you commit

The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. The README carries the MIT badge and the repository root contains a LICENSE file. Nothing in the README suggests dual licensing or a separate commercial tier, but this is a description of the licence text, not legal advice; read LICENSE yourself if your organisation has rules about bundled agent skills.

On maintenance, the last push was on 2026-09-14, three days before this writing, and the repository is not archived. Three releases, v0.4.1 through v0.4.3, landed between 2026-09-11 and 2026-09-14. That is a young project moving quickly, and the version-bump rule means installed copies only move when a release ships. The upgrade cost is therefore low in effort but not zero in attention: you must remember the pull before the update, and you must re-append nothing, because the routing block lives in your own CLAUDE.md and is not managed by the plugin.

One thing the README does not document is what changes between releases in detail; the release notes are named but their contents are not reproduced. If a version bump changes the report format, you will find out from the release notes rather than from a migration guide.

Editorial conclusion

Open Steps fits people who run a coding agent without reading its engineering output, and teams that want a session to end with a verdict rather than a commit hash. It does not fit anyone who needs the raw technical detail as the primary report, or who works outside Claude Code and expects every hook to behave the same. Before adopting it, run /open-steps:os-install-check in the agent and read what it marks as not checked, then confirm the routing block actually landed in ~/.claude/CLAUDE.md, because that block is what makes the style a rule instead of a suggestion.

Frequently asked questions

Official sources

1. kharmanskyi/open-steps on GitHub
2. License: MIT
3. Project website
4. README
5. Releases