new-invariant

Creates a PreToolUse hook, test, and rule statement enforcing one project invariant.

Updated Jul 23, 2026

Search Tags:#tdd #claude code #hook #guard #pretooluse #invariant #rule enforcement

Ready to run

npx skills add https://github.com/serhii-baksheiev/create-agent-rig --skill new-invariant-serhii-baksheiev

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: new-invariant
Source: https://github.com/serhii-baksheiev/create-agent-rig/tree/main/.agents/skills/new-invariant
Command: npx skills add https://github.com/serhii-baksheiev/create-agent-rig --skill new-invariant-serhii-baksheiev

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Project rules written in prose get broken repeatedly because nothing mechanically enforces them; this Skill turns one violated rule into a blocking PreToolUse hook with a test and a written rule statement. ## Core Features & Use Cases - Hook Generation from Template: Copies a working guard-invariant example hook and rewrites its scope, violation matcher, and block reason for the project's rule. - Test-Driven Enforcement: Writes the failing hook test first, covering block, allow, out-of-scope, and prose-mention false-positive cases. - Wiring and Documentation: Registers the hook in .claude/settings.json under PreToolUse and records the rule in .claude/rules/ next to the hook name. - Use Case: After a post-mortem finds service code used console.log instead of the shared logger, use this Skill to add a guard hook that blocks the violation in real editing sessions. ## Quick Start Ask the agent to turn the rule "service code never calls console.log" into an enforced invariant using the new-invariant skill.

Frequently Asked Questions about new-invariant

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I enforce a coding rule with a Claude Code hook?▼

Write a PreToolUse hook that reads the JSON payload on stdin, returns exit code 2 with a stderr reason to block, and exit 0 to allow. Register it in .claude/settings.json under the matcher for the tools it guards, such as Write|Edit.

How do I write a test for a PreToolUse hook?▼

Feed the hook a synthetic JSON payload over stdin using node --test and assert exit codes. Cover four cases: blocking the violation, allowing the compliant form, allowing out-of-scope files, and allowing prose that merely mentions the rule.

When should a rule not become an enforced invariant hook?▼

Skip the hook when the rule cannot be decided from a single edit fragment, such as complexity or naming judgments. Those belong to a code reviewer, lint rule, or type check; forcing them into a hook produces guards people fight and disable.

Why does my guard hook fire on comments and documentation?▼

The matcher is hitting prose that mentions the violation. Strip comments and string literals before matching, as the example hook does, because false positives on prose are the main reason guards get switched off.

What happens if a hook receives a malformed payload?▼

The hook should fail open and return exit code 0 on malformed JSON or internal errors. A guard that crashes and blocks everything gets deleted quickly, so the template handles parse failures by allowing the action.