florianbuetow Agent Guardrails Install
Install agent behavioral guardrail rules into the current project. Generates a bash script Stop hook and configures settings.local.json — no external plugin dependencies.
How It Works
- A bundled bash script template lives at
templates/stop-guardrails.shinside this plugin - Rule definitions in
rules/no-*.mdare the source of truth for patterns and messages - The install skill copies the template to
.claude/hooks/stop-guardrails.shin the target project - The script is registered as a Stop hook in
.claude/settings.local.json - No runtime dependencies — just bash, jq, and grep
Curated Rule Set
Rule definitions: plugins/agent-guardrails/rules/no-*.md
Bundled script: plugins/agent-guardrails/templates/stop-guardrails.sh
| # | Rule | Description |
|---|---|---|
| 1 | no-guessing |
Blocks hedging, guessing, unverified claims |
| 2 | no-stalling |
Blocks stalling language, padding before action |
| 3 | no-preference-asking |
Blocks delegating decisions to the user |
| 4 | no-false-completion |
Blocks unverified completion claims |
| 5 | no-skipping |
Blocks skipping work or hand-waving |
| 6 | no-dismissing |
Blocks dismissing issues without investigation |
| 7 | no-cosmetic |
Blocks calling anything cosmetic |
| 8 | no-caveats |
Blocks reporting caveats instead of acting on them |
| 9 | no-flagging |
Blocks flagging issues instead of resolving them |
Workflow
Step 1: Check Current State
Check what guardrail files already exist in the project:
ls .claude/hooks/stop-guardrails.sh 2>/dev/null
cat .claude/settings.local.json 2>/dev/null
Step 2: Determine What to Install
If $ARGUMENTS contains specific rule names (e.g., "install no-stalling no-skipping"):
- Copy the template, then remove the grep blocks for rules NOT in the list.
If $ARGUMENTS mentions "all" or "curated" (e.g., "install all"):
- Copy the full template as-is.
If $ARGUMENTS is empty:
- Copy the full template as-is. This is the default — do not ask the user to choose.
Step 3: Create Directories
mkdir -p .claude/hooks
Step 4: Copy the Bash Script Template
Read the bundled template from ${CLAUDE_PLUGIN_ROOT}/templates/stop-guardrails.sh and write it to .claude/hooks/stop-guardrails.sh in the target project.
If only a subset of rules was requested (Step 2), remove the unwanted grep blocks from the copied script before writing.
If the user has an existing .claude/hooks/stop-guardrails.sh with custom rules (grep blocks not in the curated set), preserve those custom blocks when overwriting.
Step 5: Make Script Executable
chmod +x .claude/hooks/stop-guardrails.sh
Step 6: Configure settings.local.json
Read the existing .claude/settings.local.json if it exists. Merge the Stop hook entry into it, preserving any existing hooks and permissions.
The Stop hook entry to add:
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-guardrails.sh",
"timeout": 5000
}
]
}
]
}
}
If a Stop hook for stop-guardrails.sh already exists, leave it as-is (just update the script file).
Step 7: Verify Installation
After writing all files, verify:
ls -la .claude/hooks/stop-guardrails.sh
head -5 .claude/hooks/stop-guardrails.sh
cat .claude/settings.local.json | jq '.hooks.Stop'
Step 8: Report Results
Show what was installed:
## Agent Guardrails Installed
| Rule | Status |
|------|--------|
| no-guessing | Installed |
| no-stalling | Installed |
| no-preference-asking | Installed |
| no-false-completion | Installed |
| no-skipping | Installed |
| no-dismissing | Installed |
| no-cosmetic | Installed |
| no-caveats | Installed |
| no-flagging | Installed |
**Script:** `.claude/hooks/stop-guardrails.sh`
**Config:** `.claude/settings.local.json` (Stop hook)
**Runtime:** bash + jq + grep (no plugin dependencies)
**Effect:** Requires a session restart. Run `/exit` and start a new Claude session for hooks to take effect.
Rules trigger on the assistant's Stop event. To test after restarting, run `/agent-guardrails:test`.
**To customize:** Edit `.claude/hooks/stop-guardrails.sh` directly.
**To add/remove rules:** Re-run /agent-guardrails:install with specific rule names.
**To refine:** Run /agent-guardrails:update after using the rules for a few sessions.
Custom Rules
If the user provides a custom behavior description (not one of the nine curated rules), add a new grep block to the bash script following the same pattern:
# {kebab-case-name}
if echo "$message" | grep -qiE '{pattern}'; then
blocked+=("**{kebab-case-name}**: {message}")
fi