🇬🇧 English · 🇷🇺 Русский

SUPERSTACK

Say what you want built. Get a version whose "done" was closed by an exit code, not by a sentence in the chat.

1969 tests · 561 mutations, all caught · 319 mechanisms.

What this is

SUPERSTACK is a plugin for Claude Code. You describe a product in your own
words — "I want a site where people book a haircut" — and it carries the job
all the way to a version that was actually checked. The rule the whole thing is
built around is short: a report is a claim, not a proof. "Should work" and
"tests should pass" mean the work is not done.

Here is what that looks like for the haircut site. It writes your sentence down
verbatim, then asks only the handful of questions you alone can answer — who
books, what happens on a double booking, what the client sees afterwards — and
measures everything else itself. It turns the answers into a requirements list
and a spec, designs the interface on a canvas and pulls the real values into the
code instead of retelling them, and shows you a plan. You approve the plan
before a single line of code exists. Then the tasks go out to a builder agent,
one fresh context per task, and the result is put in front of commands whose
exit code decides whether the turn may close.

Before it says "done", a separate agent reads only your original sentence and
the diff — no spec, no plan, no conversation — and answers one question: is this
what was asked for? What you get at the end is a report with a How to open it
section. An address, not a status.

It also knows how to look at your Claude Code setup, explain where every finding
came from, and change nothing without asking.

Why

An exit code closes the turn, not a sentence. The end-of-session check in
hooks/verify-gate.py runs the project's own commands; while they return
non-zero the turn stays open, and no wording in the chat can close it.

Blind acceptance before the word "done". A separate agent
(agents/blind-acceptance.md) is handed your original request and the diff and
nothing else, so it grades what was asked for instead of agreeing with the plan
it just read.

Snapshots at every stage boundary, so "put it back" is one sentence.
tools/checkpoint.py snapshots the product folder before and after every edit;
/oops shows you what would come back before it returns anything. Nothing in
this system is deleted — removals go to quarantine, and a backup is written
before the first change.

Plain language enforced by code, not by good intentions. Jargon is
impossible to proofread out of your own writing — to notice an opaque word you
have to stop understanding it. The product talks to you in Russian, and
tools/plain_ru.py keeps that word list as data, finds the jargon by machine,
and answers with an exit code.

No dependencies at all. Python 3 and the standard library — 72 tools, about
24,800 lines, zero third-party packages, nothing to install, nothing to audit
downstream.

The plugin holds itself to the bar it sells. Nine gates, and the harshest is
mutation: 561 registered mutations break the code on purpose, and every one
of them must turn the suite red. A check that cannot fail is not a check.

Quick start

Without opening a terminal

The plugin only works in Claude Code. Paste this text to your Claude Code and it
will do the rest itself:

Install SUPERSTACK for me. Run exactly these three commands in the terminal, one
at a time, and do not stop if the first one comes back red:

CLAUDECODE= claude plugin marketplace add edvardgrishin27/superstack-plugin
CLAUDECODE= claude plugin marketplace update superstack
CLAUDECODE= claude plugin install superstack@superstack

On a machine where SUPERSTACK was installed before, the first command answers
"Marketplace 'superstack' is already installed" and exits with code 1. That is
NOT a failed install and not a reason to stop: the marketplace is simply already
there. Keep going.

The second command is the one this whole text was rewritten for. Without it, such
a machine takes the OLD package list from its cache and installs the previous
version. It looks successful: green command, plugin installed, wrong version. On
a clean machine it is harmless, which is why it always runs.

The CLAUDECODE= prefix is required: without it `claude` refuses to start from
inside a session ("cannot be launched inside another Claude Code session"), and
that is not a bug — it is the guard against nested sessions.

Install nothing else. When you are finished, say in one line that it is done, and
tell the person to restart the whole application — not a new chat in the same
window: quit it completely (Cmd+Q on a Mac) and open it again. Plugins are read
at startup.

Verified by running it, not reasoned about: both sequences were executed against
an isolated config (CLAUDE_CONFIG_DIR), on a clean machine and again on top of
an existing install. Both ended on a working version.

From a terminal

claude plugin marketplace add edvardgrishin27/superstack-plugin
claude plugin marketplace update superstack
claude plugin install superstack@superstack

No prefix needed here — you are already outside a session. On a machine that
already has the marketplace, the first line exits with code 1; that is fine, the
second line fixes it.

Then quit Claude Code completely (Cmd+Q on a Mac) and open it again. After that
you can just talk to it — there are no magic words to memorise.

Commands

Seven commands. You never have to type them: each one also answers to ordinary
language, which is what the middle column is for.

How it works

/go runs in phases, and the code is written in the second-to-last one. Every
phase before it establishes what to build; every phase after it proves that
this is what got built.

flowchart TD
    A["Your sentence:<br/>“I want a booking site”"] --> B["0 · Open<br/>brief recorded verbatim, progress panel opens"]
    B --> C["1 · Understand<br/>G1 — not one requirement left open"]
    C --> D["2 · Spec<br/>G2 — reviewed by other eyes, folder set up from the spec"]
    D --> E["2.5 · Direction<br/>design on a canvas — only if the product has an interface"]
    E --> F["3 · Plan<br/>G3 — traces to requirements both ways<br/><b>you approve; no code before this</b>"]
    F --> G["4 · Work<br/>one task per builder agent, in a fresh context"]
    G --> H["5 · Verification<br/>verify.py ≠ 0 keeps the turn open"]
    H --> I["5.4 · Security<br/>only if the product faces real people"]
    I --> J["5.5 · Look at it<br/>open the page before showing it to anyone"]
    J --> K["6 · Blind acceptance<br/>G4 — request and diff only, nothing else"]
    K --> L["7 · What survives<br/>project memory, decisions, document links"]
    L --> M["8 · Report<br/>assembled from files, with “How to open it”"]

Skipping a phase is allowed; skipping it silently is not. When the design phase
or the security phase does not apply, it says so in one line — because "we
decided it wasn't needed" and "we forgot" look identical otherwise.

Under the hood

Python 3 and the standard library. Nothing else. 72 tools (about 24,800 lines),
7 skills, 3 agents, and three automatic checks wired into the session: one at
start-up, one before the context is compacted, one at the end of a turn.

The mechanisms worth naming, each of them a file you can open:

The bar the plugin holds itself to

Nine gates, run by tools/gauntlet.py. Numbers below are measured, not typed in.

The counts at the top of this page — badges and summary line — are rewritten by
measurement at release time (tools/sync_public.py), in both language versions.
A showcase for a product that promises never to claim the unmeasured does not
get to type its own figures.

Requirements and platforms

• Claude Code, desktop app or terminal. The plugin runs nowhere else —
  claude plugin … exists only here.
• Python 3.8 or newer, whatever the system already has. The floor comes from
  the syntax in the code: assignment expressions (:=) are used, nothing newer
  is. No third-party packages, at any version.
• pytest, only if you want to run the test suite.
• macOS and Linux — run live, end to end.
• Windows — the code paths are there (file locking falls back to msvcrt
  where fcntl is absent; the process-alive probe knows os.kill behaves
  differently), but no live run has ever been done. That is a status, not a
  disclaimer: tools/platform_check.py says it out loud at the start of a
  session and names what stops working — self-launch where the interpreter is
  not called python3, non-ASCII output in the Windows console, and the
  one-line .sh wrappers next to the tools.

Status

Version 0.10.0. All nine gates green on the tree this text ships from.

Known not done, and said here rather than discovered later:

• No live run with a newcomer who has never installed it. Everything about the
  first-time experience is reasoning, not observation.
• Windows has never been run live. See above.

Contributing

The rule for anything new is fixed, and it runs in this order:

mechanism → map → test → mutation → code.

A mechanism is finished when it exists in data/plan-coverage.json with an
evidence file and a literal substring of executable text, has a test in tests/,
and has a registered breakage in tests/mutations.json that actually turns the
suite red. A mechanism nothing can break is not a mechanism.

python3 -m pytest tests/ -q          # the suite
python3 tools/gauntlet.py --quick    # fast loop: skips mutations and hermetic
python3 tools/gauntlet.py            # everything, roughly two hours

--quick exits with code 2 by design — two gates are not run in it, and
"skipped" is deliberately not "passed".

License

MIT — see LICENSE.

Up to version 0.3.0 the system shipped as seven packages (superstack-core,
-install, -spec, -guard, -build, -brain, -control). There is one
package now, and the old seven have to be removed — otherwise two copies of the
same skills sit side by side and either of them can be picked up by description.

In the desktop app: settings → plugins, remove each of the seven old ones,
then update the superstack marketplace and install superstack. The order
matters twice. While the old ones are still there, two copies of the same skills
sit side by side. And without updating the marketplace, the old cached list is
used — the one with seven packages — and the previous version gets installed,
looking no different from the new one.

Why the split is gone. Seven packages would have made sense if they were
installed and updated separately. Neither ever happened once: the whole set went
in together and was updated together, seven identical actions in a row. The price
was cross-package addressing — a skill in one package calling a tool in another
through a path that does not exist inside its own package. That is how 14 tools
out of 29 once became unreachable, and how both calls in the only build skill
pointed at nothing for several runs. One package removes that whole class of
failure instead of patching it with another check.

The /plugin slash command will not help. It exists only in terminal Claude
Code; the desktop app does not have it, and trying it there answers "isn't
available in this environment". Verified on the desktop, not inferred.