{
  "markdown": "<div align=\"center\">\n\n```\n███████╗████████╗███████╗████████╗██╗  ██╗███████╗███████╗██████╗ \n██╔════╝╚══██╔══╝██╔════╝╚══██╔══╝██║ ██╔╝██╔════╝██╔════╝██╔══██╗\n███████╗   ██║   █████╗     ██║   █████╔╝ █████╗  █████╗  ██████╔╝\n╚════██║   ██║   ██╔══╝     ██║   ██╔═██╗ ██╔══╝  ██╔══╝  ██╔═══╝ \n███████║   ██║   ███████╗   ██║   ██║  ██╗███████╗███████╗██║     \n╚══════╝   ╚═╝   ╚══════╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚══════╝╚═╝     \n```\n\n### *XML protocol framework + false-positive catalog for Claude Code.*\n\n**Stop Claude from \"helpfully\" refactoring your intentional code.**\n\n[![npm](https://img.shields.io/npm/v/stetkeep?color=CB3837&logo=npm)](https://www.npmjs.com/package/stetkeep)\n[![License: MIT](https://img.shields.io/badge/License-MIT-A78BFA.svg)](https://opensource.org/licenses/MIT)\n[![Claude Code](https://img.shields.io/badge/Built%20for-Claude%20Code-D4A27F)](https://claude.com/claude-code)\n[![Version](https://img.shields.io/github/v/release/chanjoongx/stetkeep?include_prereleases&color=5FE5D4&label=version)](https://github.com/chanjoongx/stetkeep/releases)\n[![Provenance](https://img.shields.io/badge/npm-sigstore%20provenance-34D399?logo=sigstore)](https://www.npmjs.com/package/stetkeep)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-7AB7FC)](CONTRIBUTING.md)\n\n</div>\n\n---\n\n## ⚡ 30-second install\n\n```bash\nnpx stetkeep install\n```\n\nThis is the one-command minimal install: protocols, subagents, slash commands, path-scoped rules. Next session of `claude`, type `/brain-scan` and you're working.\n\nFor full mechanical enforcement (hooks + permissions deny-lists), the **Install** section below has a two-step recommended flow: one extra `cp` command.\n\nFull walkthrough: [`BOOTSTRAP_GUIDE.md`](BOOTSTRAP_GUIDE.md).\n\n---\n\n## 🎯 What stetkeep actually is\n\nTwo things other Claude Code projects don't ship:\n\n### 1. **XML-structured protocol framework**\n\nProse prompts (\"be careful when refactoring, prefer readability over cleverness...\") don't survive 20K-token contexts. XML-tagged directives do. [Anthropic's own prompting guide](https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/use-xml-tags) recommends XML tags explicitly as a way for Claude to parse prompts more accurately. We built three protocols around it:\n\n- **BRAIN.md** — `<routing>` / `<mode>` / `<inhibit>` — decides where a command goes\n- **CRAFT.md** — `<anti_patterns>` / `<safety_net>` / `<false_positives>` — structural refactor discipline\n- **PERF.md** — `<pre_check>` / `<perf_budget>` / `<measurement_gate>` — measurement-first performance work\n\n~1–2K tokens each (BRAIN ~1K · CRAFT ~1.5K · PERF ~1.8K). Claude's attention lands on XML-delimited sections more reliably than on Markdown prose headers.\n\n### 2. **False-positive catalog**\n\nThe 16-entry registry of \"patterns Claude will mistakenly flag as problems.\" Examples:\n\n| What Claude sees | What Claude will say | What it actually is |\n|---|---|---|\n| 1000-line config / data file | \"God File (A1). Split it.\" | A data table. Splitting loses context. |\n| Deliberate inline `for` loop | \"Duplication (A3). Extract.\" | Profiled hot path. 10× faster than `reduce`. |\n| Plain `<img>` element | \"Use `next/image`.\" | Below-fold. Not the LCP element. |\n| `Array.map().map().map()` | \"Collapse into `reduce`.\" | V8 optimizes this; readability wins. |\n\nWhen Claude matches one of these, the Safety Net flags it 🔴 Low confidence and asks before editing. Catalog is under `<false_positives>` in CRAFT.md and PERF.md.\n\nNo competitor ships this.\n\n---\n\n## 🛡 Supporting layer — hook-enforced Safety Net\n\nOn top of the XML framework, stetkeep ships a five-layer defense:\n\n- **Layer A** — `permissions.deny` hard-blocks edits to `legacy/`, `generated/`, `vendor/` (deterministic)\n- **Layer B** — PreToolUse hook runs out-of-process; returns `deny`/`ask`/`allow` JSON (deterministic)\n- **Layer C** — Subagent tool scoping — `craft-specialist` / `perf-specialist` can't create new files; edits to existing files require explicit user approval (structural)\n- **Layer D** — Path-scoped rules auto-load CRAFT/PERF on `src/**` file access (heuristic)\n- **Layer E** — XML protocols + false-positive catalog (heuristic)\n\nLayers A / B / C fire regardless of model attention. Layers D / E bias behavior. Honest breakdown in [`ARCHITECTURE.md §1`](ARCHITECTURE.md#1-enforcement-layers).\n\nThis part is **not novel** — [TDD-Guard](https://github.com/nizos/tdd-guard), [claude-guardrails](https://github.com/dwarvesf/claude-guardrails), and others already ship hook-based enforcement. stetkeep's wedge is the XML framework + FP catalog above; hooks are just the vehicle.\n\n---\n\n## 🧠 Architecture at a glance\n\n```\n                 ┌──────────────────────────┐\n  user command ─▶│     Claude Code          │\n                 │  (reads CLAUDE.md auto)  │\n                 └───────────┬──────────────┘\n                             │\n               ┌─────────────┴─────────────┐\n               ▼                           ▼\n   ┌────────────────────┐    ┌──────────────────────┐\n   │ Subagents          │    │ Path-scoped rules    │\n   │ agents/            │    │ .claude/rules/       │\n   │ — tool-scoped      │    │ — auto-load on read  │\n   └──────────┬─────────┘    └──────────┬───────────┘\n              │                          │\n              └──────────────┬───────────┘\n                             ▼\n                  ┌──────────────────────┐\n                  │  Edit / Write tool   │\n                  └──────────┬───────────┘\n                             │\n                 ┌───────────▼────────────┐\n                 │ PreToolUse HOOK        │  ◀── mechanical, out-of-process\n                 │ hooks/safety-net.sh    │     can deny / ask / allow\n                 │ path / ignore / marker │     path, ignore, marker-driven\n                 └───────────┬────────────┘\n                             │\n                        allow│deny/ask\n                             ▼\n                    ┌──────────────┐\n                    │   file edit  │\n                    └──────────────┘\n```\n\n---\n\n## 📦 Install\n\n### Quickstart (1 step, minimal)\n\n```bash\ncd /path/to/your-project\nnpx stetkeep install\n```\n\nGets you the XML protocols, subagents, slash commands, and path-scoped rules (Layers C/D/E). Enforcement is prompt-level only: the model biases toward the Safety Net but cannot be mechanically blocked.\n\n### Recommended (2 steps, full mechanical enforcement)\n\nAfter `npx stetkeep install`:\n\n```bash\ncp .claude/settings.example.json .claude/settings.json\n```\n\n> **If you already have `.claude/settings.json`** (from other tooling or a previous install): `cp` will overwrite it. Run `ls .claude/settings.json` first; if it exists, merge the `permissions` and `hooks.PreToolUse` blocks from `settings.example.json` manually instead of overwriting.\n\nThis wires up the remaining two layers:\n\n- **Layer A** (permissions deny-list): hard-blocks edits to `legacy/`, `generated/`, `vendor/`\n- **Layer B** (PreToolUse hook): out-of-process Safety Net enforcement on every Edit / Write / Bash\n\nWithout this step, `legacy/` protection is a prompt suggestion rather than a deterministic block. You keep the same protection surface the project was designed around by completing it.\n\n### Then launch\n\n```bash\nclaude\n```\n\nInside Claude Code:\n```\n/brain-scan\n```\n\n### `npx stetkeep install` modes\n\n- `--mode coexist` (default): preserve everything, append 3-line bootstrap to CLAUDE.md\n- `--mode merge`: same + add a Protocols reference section\n- `--mode fresh`: empty-project install (requires `--force` if anything exists)\n- `--dry-run`: preview without writing\n\n### Alternative: self-hosted plugin marketplace\n\nstetkeep distributes a plugin catalog directly from GitHub — no Anthropic review required, works today:\n\n```\n# In Claude Code\n/plugin marketplace add chanjoongx/stetkeep\n/plugin install stetkeep\n```\n\nAuto-loads subagents, commands, and the hook with no file copying into your project. Tradeoff: path-scoped rules (Layer D) and root-level protocol MDs cannot be packaged by the plugin spec, so they stay user-level. For the full experience use `npx stetkeep install`.\n\n### Anthropic official marketplace (under review)\n\nstetkeep has been submitted to Anthropic's official Claude Code plugin marketplace and is currently under review. Once approved, installation simplifies to a single command — no `marketplace add` step needed:\n\n```\n# In Claude Code — available once approved\n/plugin install stetkeep\n```\n\nWatch [chanjoongx/stetkeep](https://github.com/chanjoongx/stetkeep) releases for updates.\n\n### Alternative: clone + run installer directly (for hacking on stetkeep)\n\n```bash\ngit clone https://github.com/chanjoongx/stetkeep.git\ncd /path/to/your-project\nnode /path/to/stetkeep/lib/install.js\n```\n\nSame flags as `npx stetkeep install` (`--mode`, `--force`, `--dry-run`). Use this only if you are modifying stetkeep itself.\n\n---\n\n## 🚀 Usage\n\nAfter install, three slash commands are available inside Claude Code. Type `/` to see them:\n\n| Command | What it does |\n|---|---|\n| `/brain-scan [path]` | Map your MD ecosystem — classifies all `.md` files, checks Safety Net wiring, proposes next steps |\n| `/craft-audit [path]` | Read-only structural scan — A1–A20 anti-pattern atlas + false-positive cross-check, returns 🟢/🟡/🔴 confidence-graded findings |\n| `/perf-audit [scope]` | Measurement-first baseline — guides Lighthouse + bundle analysis, returns Top 5 bottlenecks by Impact × User-pain |\n\n**Recommended first session:**\n\n```\n/brain-scan            # map what's in your project, check Safety Net status\n/craft-audit src/      # find structural issues — read-only, no edits yet\n/perf-audit            # baseline measurements — read-only, no edits yet\n```\n\nBoth audit commands end with *\"Proceed? (yes / reorder / cancel)\"* — nothing is edited without an explicit go-ahead.\n\n---\n\n## ⚙️ Requirements\n\n- **Claude Code 2026+** (hooks, subagents, path-scoped rules, slash commands all require this)\n- **Node 20+** (bundled with Claude Code — you have it)\n- **bash** on macOS/Linux; **Git Bash** (recommended) or **PowerShell** on Windows\n- **jq** (optional — hook falls back to grep if absent)\n\n> **Windows note**: macOS/Linux/Git Bash is the primary test surface. The `safety-net.ps1` PowerShell hook ships but has less field data; if hooks misbehave on native PowerShell, `npx stetkeep install` is the shortest recovery path (bypasses ExecutionPolicy + avoids the WSL `bash.exe` proxy).\n\n---\n\n## ⚖ vs. the 2026 ecosystem\n\nHonest comparison (based on competitive research documented in [CHANGELOG v0.3.0](CHANGELOG.md)):\n\n| | **stetkeep** | [TDD-Guard](https://github.com/nizos/tdd-guard) | [claude-guardrails](https://github.com/dwarvesf/claude-guardrails) | [VoltAgent subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) | [everything-claude-code](https://github.com/affaan-m/everything-claude-code) |\n|---|---|---|---|---|---|\n| **Scope** | XML protocols + FP catalog | TDD-specific blocking | Security permissions | Subagent library | Kitchen-sink toolkit |\n| **Stars (Apr 2026)** | just launched | 2K | 12 | 17.7K | 160K |\n| **Hook enforcement** | ✅ | ✅ | ✅ | ❌ | ✅ |\n| **Tool-scoped subagents** | ✅ | ❌ | ❌ | ✅ | ✅ |\n| **XML-structured protocols** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **False-positive catalog** | ✅ | ❌ | ❌ | ❌ | ❌ |\n| **Plugin marketplace** | ✅ | ✅ | ❌ | ✅ | ✅ |\n| **npm package** | ✅ | ✅ | ✅ | ❌ | ✅ |\n\nIf you want **TDD-specific blocking** → TDD-Guard. If you want **security policy as code** → claude-guardrails. If you want **an agent library** → VoltAgent. If you want **everything at once** → everything-claude-code.\n\nIf you want **a protocol framework with a curated false-positive registry**, that's us.\n\n---\n\n## 🎯 Verify it works\n\n> Checks 1-3 assume the `npx stetkeep install` flow, which copies files into your project's `.claude/`. Plugin-marketplace installs register the artifacts from Claude Code's own plugin directory, so `.claude/agents/` and `.claude/hooks/` will be empty in your project; in that case skip to check 4.\n\n```bash\n# 1. Hook runs and returns decisions\necho '{\"tool_name\":\"Edit\",\"tool_input\":{\"file_path\":\"legacy/x.ts\"}}' \\\n  | bash .claude/hooks/safety-net.sh\n\n# Expected (JSON):\n# {\"hookSpecificOutput\":{\"permissionDecision\":\"ask\", ...}}\n\n# 2. Subagents discoverable\nls .claude/agents/\n# brain-router.md  craft-specialist.md  perf-specialist.md\n\n# 3. Slash commands (after restarting Claude Code)\n# In Claude Code, type `/` — you should see /brain-scan, /craft-audit, /perf-audit\n\n# 4. Quick diagnostic (works in both install modes)\nnpx stetkeep scan\n```\n\n---\n\n## 🔧 Troubleshooting\n\n### Windows PowerShell execution policy issues\nUse `npx stetkeep install` — it runs through npm and is not affected by PowerShell's ExecutionPolicy.\n\n### PowerShell renders em-dashes (`—`) as `??`\nCosmetic only on Korean / CP949 consoles. Run `chcp 65001` first, or just ignore — the install is correct.\n\n### `bash` in PowerShell tries to invoke WSL\nThat's Windows's built-in `bash.exe` (WSL proxy), not Git Bash. Use `npx stetkeep install` (no bash dependency) or open Git Bash directly from the Start menu.\n\n### Hook doesn't seem to do anything\nVerify the hook returns JSON:\n```bash\necho '{\"tool_name\":\"Edit\",\"tool_input\":{\"file_path\":\"legacy/x.ts\"}}' | bash .claude/hooks/safety-net.sh\n```\nIf no output: make sure `.claude/settings.json` exists (copy from `settings.example.json`) and the hook is wired under `hooks.PreToolUse`.\n\n### `/brain-scan` not recognized\nClaude Code 2026+ required. Older versions don't scan `.claude/commands/`. Check with `claude --version`.\n\n---\n\n## 📁 Repo layout\n\n```\nstetkeep/\n├── agents/                      # plugin subagents (canonical, marketplace-distributed)\n├── commands/                    # plugin slash commands (canonical)\n├── hooks/\n│   ├── hooks.json               # plugin hook manifest\n│   ├── safety-net.sh            # PreToolUse (bash)\n│   └── safety-net.ps1           # PreToolUse (PowerShell)\n├── .claude/                     # dogfooding mirrors + user-level files\n│   ├── agents/                  # mirror of ../agents/ (loaded when claude runs inside this repo)\n│   ├── commands/                # mirror of ../commands/\n│   ├── hooks/                   # mirror of ../hooks/\n│   ├── rules/                   # path-scoped rules (npm-distributed; plugin spec cannot package these)\n│   └── settings.example.json    # hook wiring template\n├── .claude-plugin/\n│   ├── plugin.json              # Claude Code plugin manifest\n│   └── marketplace.json         # self-hosted marketplace entry\n├── bin/stetkeep.js               # npm CLI entry (ESM, Node 20+, stdlib only)\n├── lib/\n│   ├── install.js               # cross-platform installer\n│   ├── scan.js                  # ecosystem diagnostic\n│   └── utils.js                 # log helpers\n├── BRAIN.md                     # routing protocol\n├── CRAFT.md                     # refactor protocol + FP catalog\n├── PERF.md                      # performance protocol + FP catalog\n├── CLAUDE.template.md           # user-facing CLAUDE.md template (npm-distributed)\n├── ARCHITECTURE.md              # honest enforcement breakdown\n├── BOOTSTRAP_GUIDE.md           # first-session walkthrough\n├── PRIVACY.md                   # privacy policy (zero data collection)\n├── benchmark/SPEC.md            # evaluation methodology\n├── docs/releases/               # per-version release notes (source)\n├── validators/                  # installation verification (.sh + .ps1)\n├── package.json\n├── CHANGELOG.md\n├── CONTRIBUTING.md\n└── LICENSE\n```\n\n---\n\n## 🧪 Benchmark\n\nWe publish a pre-registered evaluation spec instead of hand-wavy numbers:\n\n📄 [`benchmark/SPEC.md`](benchmark/SPEC.md) — 50 test cases, 3 conditions (vanilla / stetkeep full / stetkeep Safety-Net-only), human rubric grading (Cohen's κ ≥ 0.75), paired bootstrap statistics.\n\nResults pending. We'll publish data + methodology, not a single percentage.\n\n---\n\n## ❓ FAQ\n\n### Does the Safety Net actually work, or is it prompting theater?\nLayers A (permissions) and B (hook) are out-of-process and deterministic — they block edits before the tool fires, regardless of what Claude decided. Layer C (subagent tool scoping) is enforced at spawn — `Write` (new file creation) is not in the toolset; `Edit` of existing files requires explicit user approval. Layers D (path-scoped rules) and E (XML protocols + FP catalog) are heuristic — they bias the model but cannot guarantee behavior. Full breakdown in [ARCHITECTURE.md §1](ARCHITECTURE.md#1-enforcement-layers).\n\n### Does this work with Cursor / Codex / OpenCode?\nThe XML protocols and false-positive catalog are plain Markdown — any AI that reads MD can use them. But the hook system, subagent tool scoping, and path-scoped rules are Claude Code 2026 features. Without them you lose the deterministic layers.\n\n### Why BRAIN / CRAFT / PERF?\nIt's a mnemonic — \"BRAIN routes, CRAFT refactors, PERF measures\" — not a cognitive claim. MD files are documents read by a language model. See [ARCHITECTURE.md §8](ARCHITECTURE.md#8-what-this-is-not).\n\n### Does it work with existing `CLAUDE.md` and `memory/`?\nYes. `coexist` mode (default) preserves everything — only appends a 3-line bootstrap reference to your CLAUDE.md. The `memory/` folder is detected and left untouched.\n\n### npm install vs plugin marketplace?\n- **npm install**: gets you **everything** — the root protocols (BRAIN.md / CRAFT.md / PERF.md), path-scoped rules, settings template, plus the plugin components.\n- **Self-hosted marketplace** (`/plugin marketplace add chanjoongx/stetkeep`): gets you **only the plugin components** — subagents, slash commands, hook. Path-scoped rules and root-level protocols can't be packaged as a plugin, so they stay user-level. Works today.\n- **Official Anthropic marketplace** (`/plugin install stetkeep`): same plugin components as above, single command, no `marketplace add` step. Currently under review.\n\nFor the full stetkeep experience, use npm install. For lightweight subagent access, either plugin option works.\n\n### Why the name \"stetkeep\"?\n`stet` is the traditional editorial mark from Latin *\"let it stand\"* — what editors write over proposed deletions to cancel them and preserve the original text. `stetkeep` applies the same principle to code: tell Claude to leave your intentional code alone.\n\nOriginally launched as `mdbrain` on 2026-04-19, renamed to `stetkeep` one day later after a brand conflict with mediaire's medical AI. See [CHANGELOG](CHANGELOG.md) for the full story.\n\n### Built with AI?\nYes. Designed by [CJ Kim](https://github.com/chanjoongx) in iteration with Claude. The protocol's own Safety Net caught multiple attempts where Claude proposed to \"improve\" the protocol in self-defeating ways — which is exactly the kind of false-positive editing stetkeep is built to prevent.\n\n---\n\n## 🗺 Roadmap\n\n- [x] **v0.1** — protocol-only draft\n- [x] **v0.2** — Claude Code 2026 native mechanisms (hooks, subagents, path-scoped rules)\n- [x] **v0.3** — npm package, plugin manifest, Anthropic marketplace submission (as `mdbrain`)\n- [x] **v0.4** — renamed to `stetkeep` (brand disambiguation), post-launch audit fixes, OIDC trusted publishing + Sigstore provenance\n- [ ] **v0.5** — benchmark results (`benchmark/SPEC.md` → real numbers) + `npx stetkeep init` interactive\n- [ ] **v0.6** — per-language variants (`CRAFT.python.md`, `CRAFT.rust.md`)\n- [ ] **v1.0** — stable API, typed plugin configs\n\n---\n\n## 🤝 Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Highest-value contributions:\n\n- **New false-positive entries** — patterns Claude commonly mis-flags (with a minimal reproducer)\n- **New anti-pattern entries** (A21+, P21+) — with corresponding FP counterexamples\n- **Hook improvements** — edge cases, better path matching, platform fixes\n- **Benchmark corpus cases** — see [benchmark/SPEC.md §3](benchmark/SPEC.md)\n\n---\n\n## 🔐 Security & supply chain\n\n- Published to npm via **OIDC Trusted Publisher** (no long-lived `NPM_TOKEN`)\n- Every release carries a **Sigstore provenance attestation** (SLSA v1) bound to its source commit\n- **Zero runtime dependencies** (stdlib-only)\n- **No network calls** at install or hook time — see [`PRIVACY.md`](PRIVACY.md)\n- GitHub Actions pinned by commit SHA to prevent silent upstream changes\n\nReport vulnerabilities privately via [`SECURITY.md`](SECURITY.md).\n\n---\n\n## 📜 License\n\n[MIT](LICENSE). Use it, fork it, ship it.\n\n---\n\n<div align=\"center\">\n\n**Built by [CJ Kim](https://github.com/chanjoongx) · Stress-tested with Claude · Launched 2026-04-19**\n\n*The model is eager. The Safety Net is skeptical. The XML protocol is structured.*\n\n</div>\n",
  "bytes": 20619,
  "sha": "8bb09ad342cc1516c47b8d7ffe394817e9832ba1c34f4f2d660910c1f80bb47c",
  "repo_slug": "chanjoongx/stetkeep",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_chanjoongx_stetkeep_stetkeep_e46792e1/readme"
}