lennney/stop-that-shit

What it is

Stop That Shit (别再造史了) is a plug‑in/guard system for AI coding agents such as Codex, Claude Code, OpenCode, Hermes Agent CLI and Pi. It lets you define clear task boundaries so the agent stops doing work that the user never asked for – e.g. generating a SHA‑256 checksum that no later step reads, adding defensive code, or repeatedly re‑running the same checks.

Why it matters

When large language‑model agents are given a coding task they often add “extra” steps that consume tokens, time, and sometimes modify the repository needlessly. This project provides:

• Skill – a set of semantic rules (the Stop Ladder) that decide whether an action is truly required.
• Guard – a runtime hook that intercepts the agent’s actions (file writes, dependency installs, sub‑agent launches, hash generation, etc.) and either allows them, asks for explicit permission, or blocks them with a red STOP message.
• Adapters – thin layers that translate events from the five supported agents into a common decision interface.
• Stop‑That‑Shit Slop (STSS) – a separate skill that trims unnecessary defensive language from the agent’s textual output.

Together they keep the agent focused, reduce token waste, and prevent accidental “scope creep” in automated coding pipelines.

How you use it

1. Install the plug‑in for your agent (Node ≥ 18 for most, Node ≥ 22 for Pi). The README gives one‑line commands for each supported host.
2. Run the skill via the host’s CLI, e.g.:

   $stop-that-shit review -- Review this diff, don’t modify.
   $stop-that-shit change hash=allow -- Generate the checksum I explicitly asked for.
   

3. Specify contracts when needed, such as files=src/config.cjs|test/config.test.cjs to limit which paths the agent may touch, or deps=allow to auto‑approve dependency installs.
4. The guard starts in observing mode (records actions but does not block). Switching to review, answer, monitor or change arms it; then any disallowed action triggers a clear STOP response:

   STOP / INTENT
   Guard returns permission deny.
   Reason: MODE_FORBIDS_MUTATION
   

5. For text‑only cleanup, install the STSS skill and run $stss rewrite … or $stss audit … to drop or tighten unnecessary hedging language.

Who it’s for

• Developers who use LLM‑powered coding assistants and want deterministic, auditable builds.
• Team leads / CI pipelines that need to guarantee agents only perform actions explicitly authorized by the workflow.
• Researchers exploring safe‑guarded AI agents, as the project ships with paired evaluation data and regression tests.

What’s inside

Component	Role
Skill (Stop Ladder)	Encodes the four‑question decision flow (user request?, needed for result?, evidence?, would omission break acceptance?).
Guard (Hook)	Intercepts file writes, dependency installs, sub‑agent spawns, hash generation, etc., and enforces the Skill’s verdict.
Adapters	Translate events from Codex, Claude Code, OpenCode, Hermes Agent CLI, and Pi into the common Guard interface.
STSS Skill	Applies the same decision logic to sentences, deciding to DROP, CALIBRATE, RELOCATE or KEEP defensive phrasing.
Test suite	Unit tests, paired evaluation scripts, and a set of six good/bad case bundles with offline fixtures.
Documentation	Installation guides per agent, contract syntax (files=, deps=, hash=, agents=), and a case‑library for contributors.

Maturity

• Latest stable release 0.2.1 (bug‑fix for file‑path boundary handling).
• CI builds, automated tests, and a documented release process.
• MIT‑licensed, welcoming contributions via the usual GitHub workflow.

---

All details are taken directly from the repository’s README; no additional features are inferred.