How do I install the Refactor Guarded skill?

Run npx skillmds@latest add tomevault-io/refactor-guarded in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Refactor Guarded safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Refactor Guarded?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Refactor Guarded free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Refactor Guarded?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Refactor Guarded by tomevault-io — Agent Skill

Name: Refactor Guarded
Author: tomevault-io

Refactor Guarded

Lightweight speed-bump for refactors that match the rejected-refactors list in AGENTS.md (Samsinn project). Greps for known-rejected patterns; on match, prints a one-line warning with line-pointer into AGENTS.md. NOT a gate — does not block, does not require justification. Just a friction reminder so future Codex sessions don't silently re-propose rejected work. Trigger keywords:/refactor, "refactor", "extract", "split createSystem", "replace lateBinding", "event bus", "consolidate", "MCP/REST parity", "artifact system". Use when this capability is needed.

tomevault-io Updated Sep 17, 2026

File contents

Refactor Speed-Bump

First-time setup: project-local skills are loaded at Codex session start. If this skill doesn't fire on rejected-pattern keywords right after pulling this repo, restart Codex to register.

Lightweight pattern check before proposing or implementing a refactor. Encodes the discipline of AGENTS.md's ## Rejected refactors section so it survives across sessions.

What this skill does

Match the user's refactor request against rejected patterns. The patterns:
- "replace lateBinding" / "event bus" / "pub/sub for system"
- "extract createSystem" / "split createSystem into phases" / "boot phase functions"
- "MCP/REST parity" / "tool surface unification" / "audit MCP vs REST tools"
- "revive artifacts" / "artifact system" / "workspace pane" / "task list pane" / "polls" / "shared documents"
On match, print a one-line warning with the file/line of the rejection in AGENTS.md.
Suggest: "If you have new evidence (a real bug, a second consumer, a measurable benefit), invoke Codex-toolbox:stress-test to evaluate. Otherwise, leave it alone."

What this skill does NOT do

Does NOT block the refactor. The user can override.
Does NOT require written justification.
Does NOT log the override.
Does NOT critique the refactor on its merits (that's stress-test's job).
Does NOT cover refactors not on the rejected list (those proceed normally).

Implementation

Read AGENTS.md, locate the ## Rejected refactors section. For each bullet:

Extract the headline phrase (e.g. "Replacing lateBinding in main.ts with an event bus").
Match the user's request against the headline + body keywords.

Print:

⚠️  This refactor matches a rejected pattern in AGENTS.md:36+

   "<headline of the matched bullet>"

   Per AGENTS.md: revisit only if you can demonstrate a *significant* new
   benefit (a bug traced to the pattern, a second-consumer use case, a
   measurable performance/correctness gain).

   If you have such evidence: run `Codex-toolbox:stress-test` next.
   Otherwise: leave this alone.

Then continue with normal flow. The user decides whether to proceed.

Why a speed-bump and not a gate

The rejected list is human judgment, not algorithmic. A gate that demanded written justification would either:

get rubber-stamped (everyone clicks "yes I have evidence" without thinking), or
become bureaucracy that gets bypassed.

A one-line warning with a AGENTS.md pointer forces a 5-second pause and re-read. That's enough for an honest "oh right, that's why" without becoming friction theater.

Source: michaelhil/samsinn — distributed by TomeVault.

---name: refactor-guardeddescription: Lightweight speed-bump for refactors that match the rejected-refactors list in AGENTS.md (Samsinn project). Greps for known-rejected patterns; on match, prints a one-line warning with line-pointer into AGENTS.md. NOT a gate — does not block, does not require justification. Just a friction reminder so future Codex sessions don't silently re-propose rejected work. Trigger keywords:/refactor, "refactor", "extract", "split createSystem", "replace lateBinding", "event bus", "consolidate", "MCP/REST parity", "artifact system". Use when this capability is needed.---# Refactor Speed-Bump> **First-time setup:** project-local skills are loaded at Codex session start. If this skill doesn't fire on rejected-pattern keywords right after pulling this repo, **restart Codex** to register.Lightweight pattern check before proposing or implementing a refactor. Encodes the discipline of AGENTS.md's `## Rejected refactors` section so it survives across sessions.## What this skill does1. Match the user's refactor request against rejected patterns. The patterns: - "replace lateBinding" / "event bus" / "pub/sub for system" - "extract createSystem" / "split createSystem into phases" / "boot phase functions" - "MCP/REST parity" / "tool surface unification" / "audit MCP vs REST tools" - "revive artifacts" / "artifact system" / "workspace pane" / "task list pane" / "polls" / "shared documents"2. On match, print a one-line warning with the file/line of the rejection in AGENTS.md.3. Suggest: "If you have new evidence (a real bug, a second consumer, a measurable benefit), invoke `Codex-toolbox:stress-test` to evaluate. Otherwise, leave it alone."## What this skill does NOT do- Does NOT block the refactor. The user can override.- Does NOT require written justification.- Does NOT log the override.- Does NOT critique the refactor on its merits (that's stress-test's job).- Does NOT cover refactors not on the rejected list (those proceed normally).## ImplementationRead `AGENTS.md`, locate the `## Rejected refactors` section. For each bullet:- Extract the headline phrase (e.g. "Replacing `lateBinding` in `main.ts` with an event bus").- Match the user's request against the headline + body keywords.Print:```⚠️ This refactor matches a rejected pattern in AGENTS.md:36+ "<headline of the matched bullet>" Per AGENTS.md: revisit only if you can demonstrate a *significant* new benefit (a bug traced to the pattern, a second-consumer use case, a measurable performance/correctness gain). If you have such evidence: run `Codex-toolbox:stress-test` next. Otherwise: leave this alone.```Then continue with normal flow. The user decides whether to proceed.## Why a speed-bump and not a gateThe rejected list is human judgment, not algorithmic. A gate that demanded written justification would either:- get rubber-stamped (everyone clicks "yes I have evidence" without thinking), or- become bureaucracy that gets bypassed.A one-line warning with a AGENTS.md pointer forces a 5-second pause and re-read. That's enough for an honest "oh right, that's why" without becoming friction theater.---> Source: [michaelhil/samsinn](https://github.com/michaelhil/samsinn) — distributed by [TomeVault](https://tomevault.io).

Frequently asked questions