# Agent Guardrails Adopt this skill: https://proskills.md/skills/devops/agent-guardrails Page: https://proskills.md/skills/devops/agent-guardrails This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required. ## File: SKILL.md size: 6480 sha: 8d8185fb6e6cd8c7a8016cc0212e66b53da31cb5 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/SKILL.md ````text --- name: agent-guardrails version: "1.1.0" author: "jzOcb" license: "MIT" category: "development-tools" description: "Stop AI agents from secretly bypassing your rules. Mechanical enforcement with git hooks, secret detection, deployment verification, and import registries. Born from real production incidents: server crashes, token leaks, code rewrites. Works with Claude Code, Clawdbot, Cursor. Install once, enforce forever." tags: - "ai-safety" - "code-quality" - "enforcement" - "git-hooks" - "deployment" - "security" - "automation" - "guardrails" - "claude-code" - "clawdbot" - "cursor" - "mechanical-enforcement" - "agent-reliability" keywords: - "AI agent bypassing" - "code enforcement" - "git hooks automation" - "secret detection" - "deployment verification" - "import enforcement" - "mechanical guardrails" - "agent safety" - "production incidents" - "Claude Code skills" - "Clawdbot skills" - "AI coding safety" repository: "https://github.com/jzOcb/agent-guardrails" homepage: "https://github.com/jzOcb/agent-guardrails#readme" bugs: "https://github.com/jzOcb/agent-guardrails/issues" compatibility: - "claude-code" - "clawdbot" - "cursor" - "any-ai-agent" requirements: bash: ">=4.0" git: ">=2.0" pricing: "FREE" --- # Agent Guardrails Mechanical enforcement for AI agent project standards. Rules in markdown are suggestions. Code hooks are laws. ## Quick Start ```bash cd your-project/ bash /path/to/agent-guardrails/scripts/install.sh ``` This installs the git pre-commit hook, creates a registry template, and copies check scripts into your project. ## Enforcement Hierarchy 1. **Code hooks** (git pre-commit, pre/post-creation checks) — 100% reliable 2. **Architectural constraints** (registries, import enforcement) — 95% reliable 3. **Self-verification loops** (agent checks own work) — 80% reliable 4. **Prompt rules** (AGENTS.md, system prompts) — 60-70% reliable 5. **Markdown rules** — 40-50% reliable, degrades with context length ## Tools Provided ### Scripts | Script | When to Run | What It Does | |--------|------------|--------------| | `install.sh` | Once per project | Installs hooks and scaffolding | | `pre-create-check.sh` | Before creating new `.py` files | Lists existing modules/functions to prevent reimplementation | | `post-create-validate.sh` | After creating/editing `.py` files | Detects duplicates, missing imports, bypass patterns | | `check-secrets.sh` | Before commits / on demand | Scans for hardcoded tokens, keys, passwords | | `create-deployment-check.sh` | When setting up deployment verification | Creates .deployment-check.sh, checklist, and git hook template | | `install-skill-feedback-loop.sh` | When setting up skill update automation | Creates detection, auto-commit, and git hook for skill updates | ### Assets | Asset | Purpose | |-------|---------| | `pre-commit-hook` | Ready-to-install git hook blocking bypass patterns and secrets | | `registry-template.py` | Template `__init__.py` for project module registries | ### References | File | Contents | |------|----------| | `enforcement-research.md` | Research on why code > prompts for enforcement | | `agents-md-template.md` | Template AGENTS.md with mechanical enforcement rules | | `deployment-verification-guide.md` | Full guide on preventing deployment gaps | | `skill-update-feedback.md` | Meta-enforcement: automatic skill update feedback loop | | `SKILL_CN.md` | Chinese translation of this document | ## Usage Workflow ### Setting up a new project ```bash bash scripts/install.sh /path/to/project ``` ### Before creating any new .py file ```bash bash scripts/pre-create-check.sh /path/to/project ``` Review the output. If existing functions cover your needs, import them. ### After creating/editing a .py file ```bash bash scripts/post-create-validate.sh /path/to/new_file.py ``` Fix any warnings before proceeding. ### Setting up deployment verification ```bash bash scripts/create-deployment-check.sh /path/to/project ``` This creates: - `.deployment-check.sh` - Automated verification script - `DEPLOYMENT-CHECKLIST.md` - Full deployment workflow - `.git-hooks/pre-commit-deployment` - Git hook template **Then customize:** 1. Add tests to `.deployment-check.sh` for your integration points 2. Document your flow in `DEPLOYMENT-CHECKLIST.md` 3. Install the git hook See `references/deployment-verification-guide.md` for full guide. ### Adding to AGENTS.md Copy the template from `references/agents-md-template.md` and adapt to your project. ## 中文文档 / Chinese Documentation See `references/SKILL_CN.md` for the full Chinese translation of this skill. ## Common Agent Failure Modes ### 1. Reimplementation (Bypass Pattern) **Symptom:** Agent creates "quick version" instead of importing validated code. **Enforcement:** `pre-create-check.sh` + `post-create-validate.sh` + git hook ### 2. Hardcoded Secrets **Symptom:** Tokens/keys in code instead of env vars. **Enforcement:** `check-secrets.sh` + git hook ### 3. Deployment Gap **Symptom:** Built feature but forgot to wire it into production. Users don't receive benefit. **Example:** Updated `notify.py` but cron still calls old version. **Enforcement:** `.deployment-check.sh` + git hook This is the **hardest to catch** because: - Code runs fine when tested manually - Agent marks task "done" after writing code - Problem only surfaces when user complains **Solution:** Mechanical end-to-end verification before allowing "done." ### 4. **Skill Update Gap** (META - NEW) **Symptom:** Built enforcement improvement in project but forgot to update the skill itself. **Example:** Created deployment verification for Project A, but other projects don't benefit because skill wasn't updated. **Enforcement:** `install-skill-feedback-loop.sh` → automatic detection + semi-automatic commit This is a **meta-failure mode** because: - It's about enforcement improvements themselves - Without fix: improvements stay siloed - With fix: knowledge compounds automatically **Solution:** Automatic detection of enforcement improvements with task creation and semi-automatic commits. ## Key Principle > Don't add more markdown rules. Add mechanical enforcement. > If an agent keeps bypassing a standard, don't write a stronger rule — write a hook that blocks it. > > **Corollary:** If an agent keeps forgetting integration, don't remind it — make it mechanically verify before commit. ```` ## File: README.md size: 8231 sha: fa8e3837edb1b67d45ccc5b86f833e0252b6226a upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/README.md ````text # Agent Guardrails 🛡️ [🇨🇳 中文文档](./references/SKILL_CN.md) [![Claude Code Skill](https://img.shields.io/badge/Claude_Code-Skill-8A2BE2)](https://github.com/topics/claude-code-skill) [![Clawdbot Skill](https://img.shields.io/badge/Clawdbot-Skill-blue)](https://clawdhub.com) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) [![Version](https://img.shields.io/badge/version-1.1.0-green.svg)](./VERSION) 📖 **Featured in:** [I audited my own AI agent system and found it full of holes](https://x.com/xxx111god/status/2019455237048709336) — the security audit that spawned this 5-tool security suite. ⭐ **`audit-skills.sh`** is the comprehensive audit script at the heart of the article. ## Your AI agent secretly bypasses your rules. This skill enforces them with code. **Works with:** Claude Code | Clawdbot | Cursor | Any AI coding agent > Rules in markdown are suggestions. Code hooks are laws. 🚨 **Stop production incidents before they happen** — Born from real crashes, token leaks, and silent bypasses ## The Problem You spend hours building validation pipelines, scoring systems, and verification logic. Then your AI agent writes a "quick version" that bypasses all of it. Sound familiar? ### Real Production Incidents (February 2026) **🔥 Server Crash:** Bad config edit → service crash loop → server down all night **🔑 Token Leak:** Notion token hardcoded in code, nearly pushed to public GitHub **🔄 Code Rewrite:** Agent rewrote validated scoring logic instead of importing it, sent unverified predictions **🚀 Deployment Gap:** Built new features but forgot to wire them into production, users got incomplete output This isn't a prompting problem — it's an enforcement problem. More markdown rules won't fix it. You need mechanical enforcement that **actually works**. ## Enforcement Hierarchy | Level | Method | Reliability | |-------|--------|-------------| | 1 | **Code hooks** (pre-commit, creation guards) | 100% | | 2 | **Architectural constraints** (import registries) | 95% | | 3 | **Self-verification loops** | 80% | | 4 | **Prompt rules** (AGENTS.md) | 60-70% | | 5 | **Markdown documentation** | 40-50% ⚠️ | This toolkit focuses on levels 1-2: the ones that actually work. ## What's Included | Tool | Purpose | |------|---------| | `scripts/install.sh` | One-command project setup | | `scripts/pre-create-check.sh` | Lists existing modules before you create new files | | `scripts/post-create-validate.sh` | Detects duplicate functions and missing imports | | `scripts/check-secrets.sh` | Scans for hardcoded tokens/keys/passwords | | `assets/pre-commit-hook` | Git hook that blocks bypass patterns + secrets | | `assets/registry-template.py` | Template `__init__.py` for import enforcement | | `references/agents-md-template.md` | Battle-tested AGENTS.md template | | `scripts/audit-skills.sh` | ⭐ Comprehensive security audit — scans all skills for gaps | | `references/enforcement-research.md` | Full research on why code > prompts | ## Quick Start **For Claude Code:** ```bash git clone https://github.com/jzOcb/agent-guardrails ~/.claude/skills/agent-guardrails cd your-project && bash ~/.claude/skills/agent-guardrails/scripts/install.sh . ``` **For Clawdbot:** ```bash clawdhub install agent-guardrails ``` **Manual:** ```bash bash /path/to/agent-guardrails/scripts/install.sh /path/to/your/project ``` 📖 [Claude Code detailed guide](./CLAUDE_CODE_INSTALL.md) This will: - ✅ Install git pre-commit hook (blocks bypass patterns + hardcoded secrets) - ✅ Create `__init__.py` registry template - ✅ Copy check scripts to your project - ✅ Add enforcement rules to your AGENTS.md ## Usage ### Before creating any new file: ```bash bash scripts/pre-create-check.sh /path/to/project ``` Shows existing modules and functions. If it already exists, **import it**. ### After creating/editing a file: ```bash bash scripts/post-create-validate.sh /path/to/new_file.py ``` Catches duplicate functions, missing imports, and bypass patterns like "simplified version" or "temporary". ### Secret scanning: ```bash bash scripts/check-secrets.sh /path/to/project ``` ## How It Works ### Pre-commit Hook Automatically blocks commits containing: - Bypass patterns: `"simplified version"`, `"quick version"`, `"temporary"`, `"TODO: integrate"` - Hardcoded secrets: API keys, tokens, passwords in source code ### Pre-create Check Before writing new code, the script shows you: - All existing Python modules in the project - All public functions (`def` declarations) - The project's `__init__.py` registry (if it exists) - SKILL.md contents (if it exists) This makes it **structurally difficult** to "not notice" existing code. ### Post-create Validation After writing code, the script checks: - Are there duplicate function names across files? - Does the new file import from established modules? - Does it contain bypass patterns? ### Import Registry Each project gets an `__init__.py` that explicitly lists validated functions: ```python # This is the ONLY approved interface for this project from .core import validate_data, score_item, generate_report # New scripts MUST import from here, not reimplement ``` ## Origin Story Born from a real incident (2026-02-02): We built a complete decision engine for prediction market analysis — scoring system, rules parser, news verification, data source validation. Then the AI agent created a "quick scan" script that bypassed ALL of it, sending unverified recommendations. Hours of careful work, completely ignored. The fix wasn't writing more rules. It was writing code that **mechanically prevents** the bypass. ## Research Based on research from: - [Anthropic's Claude Code Best Practices](https://code.claude.com/docs/en/best-practices) — *"Unlike CLAUDE.md instructions which are advisory, hooks are deterministic"* - [Cursor's Scaling Agents](https://cursor.com/blog/scaling-agents) — *"Opus 4.5 tends to stop earlier and take shortcuts"* - [Guardrails AI Framework](https://www.guardrailsai.com/docs) - [NVIDIA NeMo Guardrails](https://github.com/NVIDIA-NeMo/Guardrails) Full research notes in `references/enforcement-research.md`. ## For Clawdbot Users This is a [Clawdbot](https://clawd.bot) skill. Install via ClawdHub (coming soon): ```bash clawdhub install agent-guardrails ``` Or clone directly: ```bash git clone https://github.com/jzOcb/agent-guardrails.git ``` ## 中文文档 完整中文文档见 [`references/SKILL_CN.md`](references/SKILL_CN.md) ## 🛡️ Part of the AI Agent Security Suite | Tool | What It Prevents | |------|-----------------| | **[agent-guardrails](https://github.com/jzOcb/agent-guardrails)** | AI rewrites validated code, leaks secrets, bypasses standards | | **[config-guard](https://github.com/jzOcb/config-guard)** | AI writes malformed config, crashes gateway | | **[upgrade-guard](https://github.com/jzOcb/upgrade-guard)** | Version upgrades break dependencies, no rollback | | **[token-guard](https://github.com/jzOcb/token-guard)** | Runaway token costs, budget overruns | | **[process-guardian](https://github.com/jzOcb/process-guardian)** | Background processes die silently, no auto-recovery | 📖 **Read the full story:** [I audited my own AI agent system and found it full of holes](https://x.com/xxx111god/status/2019455237048709336) ## License MIT — Use it, share it, make your agents behave. ## 🛡️ Part of the OpenClaw Security Suite | Guard | Purpose | Protects Against | |-------|---------|------------------| | **[agent-guardrails](https://github.com/jzOcb/agent-guardrails)** | Pre-commit hooks + secret detection | Code leaks, unsafe commits | | **[config-guard](https://github.com/jzOcb/config-guard)** | Config validation + auto-rollback | Gateway crashes from bad config | | **[upgrade-guard](https://github.com/jzOcb/upgrade-guard)** | Safe upgrades + watchdog | Update failures, cascading breaks | | **[token-guard](https://github.com/jzOcb/token-guard)** | Usage monitoring + cost alerts | Budget overruns, runaway costs | 📚 **Full writeup:** [4-Layer Defense System for AI Agents](https://x.com/xxx111god/status/2019096285853139083) ```` ## File: scripts/check-secrets.sh size: 7014 sha: f950777eb2c65f212777835170ef7d05594a0c28 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/scripts/check-secrets.sh ```text #!/bin/bash # check-secrets.sh — Scan files for hardcoded secrets # Usage: bash check-secrets.sh [directory_or_file] # Returns exit code 1 if secrets found, 0 if clean. set -euo pipefail TARGET="${1:-.}" ERRORS=0 echo "🔐 Scanning for hardcoded secrets..." echo " Target: $TARGET" echo "" # Determine files to scan if [ -f "$TARGET" ]; then FILES="$TARGET" elif [ -d "$TARGET" ]; then FILES=$(find "$TARGET" -type f \( -name "*.py" -o -name "*.sh" -o -name "*.js" -o -name "*.ts" -o -name "*.yaml" -o -name "*.yml" -o -name "*.json" -o -name "*.env" -o -name "*.toml" -o -name "*.cfg" -o -name "*.ini" \) \ -not -path "*/.git/*" -not -path "*/node_modules/*" -not -path "*/__pycache__/*" -not -path "*/venv/*" 2>/dev/null || true) else echo "❌ Target not found: $TARGET" exit 1 fi if [ -z "$FILES" ]; then echo "ℹ️ No scannable files found." exit 0 fi # Secret patterns (PCRE) SECRET_PATTERNS=( 'token\s*=\s*["\x27][A-Za-z0-9_\-]{20,}' 'api_key\s*=\s*["\x27][A-Za-z0-9_\-]{20,}' 'secret\s*=\s*["\x27][A-Za-z0-9_\-]{20,}' 'password\s*=\s*["\x27][^\x27"]{8,}' 'Bearer [A-Za-z0-9_\-]{20,}' 'sk-[A-Za-z0-9]{20,}' 'ghp_[A-Za-z0-9]{20,}' 'xoxb-[A-Za-z0-9\-]{20,}' 'AKIA[0-9A-Z]{16}' 'eyJ[A-Za-z0-9_\-]{20,}\.[A-Za-z0-9_\-]{20,}' ) for pattern in "${SECRET_PATTERNS[@]}"; do while IFS= read -r file; do [ -z "$file" ] && continue MATCH=$(grep -Pn "$pattern" "$file" 2>/dev/null || true) if [ -n "$MATCH" ]; then echo " 🚨 POSSIBLE SECRET in $file:" echo "$MATCH" | head -3 | sed 's/^/ /' ERRORS=$((ERRORS + 1)) fi done <<< "$FILES" done # Check for os.getenv with suspicious defaults while IFS= read -r file; do [ -z "$file" ] && continue [[ "$file" != *.py ]] && continue MATCH=$(grep -n 'os\.getenv.*,.*["\x27]' "$file" 2>/dev/null | grep -iv 'default\|localhost\|http\|utf\|\.json\|\.txt\|\.log' || true) if [ -n "$MATCH" ]; then echo " ⚠️ os.getenv() with fallback in $file:" echo "$MATCH" | head -3 | sed 's/^/ /' ERRORS=$((ERRORS + 1)) fi done <<< "$FILES" # OWASP Injection Detection echo "🧪 Checking for OWASP injection patterns..." # SQL injection: string concatenation in SQL queries (not URLs) while IFS= read -r file; do [ -z "$file" ] && continue [[ "$file" =~ \.(py|js|ts|go|java|rb)$ ]] || continue MATCH=$(grep -n "\.execute\|cursor\|SELECT\|INSERT\|UPDATE\|DELETE" "$file" 2>/dev/null | \ grep -i "f\"\|format(\|%s\|sprintf\|+ \"\|concat" | \ grep -iv "parameterized\|placeholder\|prepared\|https\|http" || true) if [ -n "$MATCH" ]; then echo " ⚠️ SQL injection risk in $file:" echo "$MATCH" | head -3 | sed 's/^/ /' ERRORS=$((ERRORS + 1)) fi done <<< "$FILES" # Command injection: user input in shell commands while IFS= read -r file; do [ -z "$file" ] && continue [[ "$file" =~ \.(py|js|ts|go|java|rb)$ ]] || continue MATCH=$(grep -n "exec(\|spawn(\|system(\|popen(\|subprocess\|os\.system\|child_process" "$file" 2>/dev/null | \ grep -i "f\"\|format(\|%s\|sprintf\|\${\|+ \"\|concat" || true) if [ -n "$MATCH" ]; then echo " ⚠️ Command injection risk in $file:" echo "$MATCH" | head -3 | sed 's/^/ /' ERRORS=$((ERRORS + 1)) fi done <<< "$FILES" # Dependency vulnerability check echo "🔍 Checking dependency vulnerabilities..." # npm audit (if package.json exists) if [ -f "package.json" ] && command -v npm >/dev/null 2>&1; then echo " Running npm audit..." NPM_RESULT=$(npm audit --audit-level=high --json 2>/dev/null || echo '{"vulnerabilities":{}}') HIGH_VULNS=$(echo "$NPM_RESULT" | grep -o '"severity":"high"\|"severity":"critical"' | wc -l) if [ "$HIGH_VULNS" -gt 0 ]; then echo " 🚨 npm audit found $HIGH_VULNS high/critical vulnerabilities" ERRORS=$((ERRORS + 1)) else echo " ✅ npm audit: no high/critical vulnerabilities" fi elif [ -f "package.json" ]; then echo " ⚠️ package.json found but npm not available" fi # pip-audit (if requirements.txt exists or venv detected) if ([ -f "requirements.txt" ] || [ -f "pyproject.toml" ] || [ -d "venv" ]) && command -v pip-audit >/dev/null 2>&1; then echo " Running pip-audit..." if pip-audit --format json >/dev/null 2>&1; then echo " ✅ pip-audit: no known vulnerabilities" else echo " 🚨 pip-audit found vulnerabilities" ERRORS=$((ERRORS + 1)) fi elif [ -f "requirements.txt" ] || [ -f "pyproject.toml" ]; then echo " ⚠️ Python project detected but pip-audit not available" fi # .gitignore audit echo "🗂️ Checking .gitignore coverage..." if [ ! -f ".gitignore" ]; then echo " ⚠️ No .gitignore file found" ERRORS=$((ERRORS + 1)) else MISSING_PATTERNS=() for pattern in '.env' '.env.*' '*.key' '*.pem' '*.p12' '*.pfx' 'id_rsa' 'id_ed25519' 'credentials.json'; do if ! grep -q "$pattern" .gitignore 2>/dev/null; then MISSING_PATTERNS+=("$pattern") fi done if [ ${#MISSING_PATTERNS[@]} -gt 0 ]; then echo " ⚠️ .gitignore missing sensitive patterns: ${MISSING_PATTERNS[*]}" ERRORS=$((ERRORS + 1)) else echo " ✅ .gitignore has common sensitive patterns" fi fi # Check if sensitive files are tracked in git if [ -d ".git" ]; then TRACKED_SENSITIVE=() for pattern in '.env' '.env.*' '*.pem' '*.key' '*.p12' '*.pfx' 'credentials.json' 'service-account*.json' '*.keystore' 'id_rsa' 'id_ed25519'; do FOUND=$(git ls-files "$pattern" 2>/dev/null || true) if [ -n "$FOUND" ]; then TRACKED_SENSITIVE+=("$FOUND") fi done if [ ${#TRACKED_SENSITIVE[@]} -gt 0 ]; then echo " 🚨 Sensitive files tracked in git: ${TRACKED_SENSITIVE[*]}" ERRORS=$((ERRORS + 1)) else echo " ✅ No sensitive files tracked in git" fi fi echo "" if [ "$ERRORS" -gt 0 ]; then echo "╔══════════════════════════════════════════════════╗" echo "║ 🚨 $ERRORS security issue(s) found! ║" echo "║ Fix before committing changes. ║" echo "╚══════════════════════════════════════════════════╝" exit 1 else echo "╔══════════════════════════════════════════════════╗" echo "║ ✅ Security scan passed ║" echo "╚══════════════════════════════════════════════════╝" exit 0 fi ``` ## File: scripts/create-deployment-check.sh size: 5898 sha: f3de91aefa0a2a90f20ea9dbcc23eb0c681c702f upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/scripts/create-deployment-check.sh ````text #!/bin/bash # Create deployment verification system for a project # Usage: bash create-deployment-check.sh /path/to/project set -e if [ -z "$1" ]; then echo "Usage: $0 /path/to/project" exit 1 fi PROJECT_DIR="$1" if [ ! -d "$PROJECT_DIR" ]; then echo "Error: $PROJECT_DIR does not exist" exit 1 fi echo "🔧 Creating deployment verification system in $PROJECT_DIR" echo "" # 1. Create .deployment-check.sh template cat > "$PROJECT_DIR/.deployment-check.sh" << 'EOF' #!/bin/bash # Project Deployment Verification Script # Customize this to verify your specific integration points set -e echo "🔍 Deployment Verification" echo "==========================" echo "" FAILED=0 # Test 1: Main output generation echo "Test 1: Main output generated..." # TODO: Add your test here # Example: bash scripts/generate_report.sh > /dev/null 2>&1 # if [ -f /tmp/report.txt ]; then # echo " ✅ Report generated" # else # echo " ❌ No report" # FAILED=1 # fi echo " ⚠️ Not implemented yet" # Test 2: Output format echo "Test 2: Output format..." # TODO: Check output has required elements # Example: grep -q "Required Field" /tmp/report.txt echo " ⚠️ Not implemented yet" # Test 3: Integration points echo "Test 3: Integration points..." # TODO: Verify all entry points work echo " ⚠️ Not implemented yet" echo "" echo "==========================" if [ $FAILED -eq 0 ]; then echo "✅ All tests passed (or not yet implemented)" exit 0 else echo "❌ Some tests failed" exit 1 fi EOF chmod +x "$PROJECT_DIR/.deployment-check.sh" echo "✅ Created .deployment-check.sh" # 2. Create DEPLOYMENT-CHECKLIST.md template cat > "$PROJECT_DIR/DEPLOYMENT-CHECKLIST.md" << 'EOF' # Deployment Checklist **Problem this solves:** Built new features but forgot to wire them into production. --- ## Pre-Deployment Checklist Before marking any feature "done", verify: ### 1. Code Changes - [ ] New code written/modified - [ ] Tests pass (manual or automated) - [ ] No hardcoded secrets (run `bash check-secrets.sh`) ### 2. Integration Points - [ ] **Identify all entry points** (cron jobs, APIs, user commands) - [ ] **Update all entry points** to use new code - [ ] **Verify old code is replaced** (not running in parallel) ### 3. Configuration - [ ] Config files updated (if needed) - [ ] Environment variables set (if needed) - [ ] Documentation updated ### 4. End-to-End Test - [ ] **Run the actual production flow** (not just the function) - [ ] **Verify user-facing output** (what they see, not logs) - [ ] **Check all edge cases** (empty results, errors, etc.) ### 5. Monitoring - [ ] Logs in place - [ ] Error alerts configured - [ ] Success metrics defined --- ## Post-Deployment Verification Within 24h of deploying: - [ ] **Monitor first real run** (cron, webhook, whatever) - [ ] **Check user feedback** (did they receive expected output?) - [ ] **Review logs** (any errors/warnings?) - [ ] **Verify metrics** (is it working as expected?) --- ## Project-Specific Integration Points Example: ### Feature: Hourly Reports Entry points to check: 1. `scripts/send_hourly.sh` (cron job) 2. Heartbeat integration (message delivery) 3. Manual commands Verification steps: ```bash # Run the actual production flow bash scripts/send_hourly.sh # Check output file cat /tmp/report.txt # Verify user receives it # (check messaging platform) ``` --- ## Lessons Learned (Incident Log) ### [Date]: [Brief Description] **Symptom:** **Root cause:** **Fix:** **Prevention (added to checklist):** --- **Remember:** A feature isn't "done" until users receive the intended benefit. EOF echo "✅ Created DEPLOYMENT-CHECKLIST.md" # 3. Create git hook mkdir -p "$PROJECT_DIR/.git-hooks" cat > "$PROJECT_DIR/.git-hooks/pre-commit-deployment" << 'EOF' #!/bin/bash # Pre-commit hook for deployment verification # Runs .deployment-check.sh if project files changed # Customize this pattern to match your project files FILE_PATTERN="." # Change to your pattern, e.g., "src/", "lib/", etc. if git diff --cached --name-only | grep -q "$FILE_PATTERN"; then echo "🔍 Project files changed, running deployment verification..." if bash .deployment-check.sh; then echo "✅ Deployment checks passed" exit 0 else echo "" echo "❌ Deployment verification failed!" echo "Fix the issues above or use --no-verify to skip (not recommended)" exit 1 fi fi # No relevant changes, allow commit exit 0 EOF chmod +x "$PROJECT_DIR/.git-hooks/pre-commit-deployment" echo "✅ Created git hook template" # 4. Installation instructions cat > "$PROJECT_DIR/.deployment-setup-instructions.txt" << 'EOF' Deployment Verification Setup Complete! Files created: .deployment-check.sh - Automated verification script DEPLOYMENT-CHECKLIST.md - Full deployment workflow .git-hooks/pre-commit-deployment - Git hook template Next steps: 1. Customize .deployment-check.sh: - Add tests for your specific integration points - Verify output format, content, etc. 2. Install git hook: If this is a standalone repo: cp .git-hooks/pre-commit-deployment .git/hooks/pre-commit chmod +x .git/hooks/pre-commit If this is part of a larger repo: cd /path/to/parent-repo cp this/.git-hooks/pre-commit-deployment .git/hooks/pre-commit-yourproject # Then modify .git/hooks/pre-commit to call it 3. Document integration points in DEPLOYMENT-CHECKLIST.md 4. Run verification: bash .deployment-check.sh 5. Test git hook: # Make a change and commit - should trigger verification Remember: A feature isn't done until end-to-end production flow is verified. EOF echo "" echo "✅ Deployment verification system created!" echo "" cat "$PROJECT_DIR/.deployment-setup-instructions.txt" ```` ## File: scripts/install-skill-feedback-loop.sh size: 6239 sha: 139e3301a25c4a516ff8edd58b0ccd55ac67fbcf upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/scripts/install-skill-feedback-loop.sh ````text #!/bin/bash # Install automatic skill update feedback loop in a project # This is a meta-enforcement: ensures enforcement improvements flow back to skills set -e if [ -z "$1" ]; then echo "Usage: $0 /path/to/project [skill-name]" echo "" echo "Example: $0 /home/user/my-project agent-guardrails" exit 1 fi PROJECT_DIR="$1" SKILL_NAME="${2:-agent-guardrails}" if [ ! -d "$PROJECT_DIR" ]; then echo "Error: $PROJECT_DIR does not exist" exit 1 fi echo "🔄 Installing skill update feedback loop in $PROJECT_DIR" echo " Target skill: $SKILL_NAME" echo "" # Determine skill directory if [ -d "$PROJECT_DIR/skills/$SKILL_NAME" ]; then SKILLS_DIR="$PROJECT_DIR/skills" elif [ -d "$PROJECT_DIR/../skills/$SKILL_NAME" ]; then SKILLS_DIR="$PROJECT_DIR/../skills" else echo "⚠️ Warning: Couldn't find skills/$SKILL_NAME" echo " Will create generic configuration" fi # 1. Create detection script cat > "$PROJECT_DIR/scripts/detect-enforcement-improvement.sh" << 'DETECTION_EOF' #!/bin/bash # Auto-detect enforcement improvements and create skill update tasks # Generated by agent-guardrails/scripts/install-skill-feedback-loop.sh WORKSPACE=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) # Patterns that indicate enforcement improvements ENFORCEMENT_PATTERNS=( "\.deployment-check\.sh" "DEPLOYMENT-CHECKLIST\.md" "pre-commit" "post-create" "check-secrets" "\.guardrails" "enforcement" "mechanical" ) # Check last commit LAST_COMMIT=$(git log -1 --name-only --pretty=format:"") echo "🔍 Checking for enforcement improvements in last commit..." FOUND=() for file in $LAST_COMMIT; do for pattern in "${ENFORCEMENT_PATTERNS[@]}"; do if echo "$file" | grep -q "$pattern"; then FOUND+=("$file") break fi done done if [ ${#FOUND[@]} -eq 0 ]; then echo " No enforcement improvements detected" exit 0 fi echo "" echo "🎯 Detected ${#FOUND[@]} enforcement improvements:" for file in "${FOUND[@]}"; do echo " - $file" done echo "" # Extract info COMMIT_MSG=$(git log -1 --pretty=format:"%B") COMMIT_HASH=$(git log -1 --pretty=format:"%h") # Determine skill SKILL="agent-guardrails" if echo "$COMMIT_MSG" | grep -qi "deployment\|integration"; then SKILL="agent-guardrails" fi echo "📝 Should update skill: $SKILL" # Create task TASK_FILE="$WORKSPACE/.pending-skill-updates.txt" cat >> "$TASK_FILE" << TASK_EOF --- Date: $(date -u +"%Y-%m-%d %H:%M UTC") Commit: $COMMIT_HASH Skill: $SKILL Files: ${FOUND[@]} Commit Message: $COMMIT_MSG Action needed: 1. Review the enforcement improvement 2. Extract reusable patterns 3. Update skills/$SKILL/ 4. Run: bash scripts/auto-commit-skill-updates.sh --- TASK_EOF echo "✅ Created update task" DETECTION_EOF chmod +x "$PROJECT_DIR/scripts/detect-enforcement-improvement.sh" echo "✅ Created scripts/detect-enforcement-improvement.sh" # 2. Create auto-commit script cat > "$PROJECT_DIR/scripts/auto-commit-skill-updates.sh" << 'COMMIT_EOF' #!/bin/bash # Auto-commit skill updates with confirmation # Generated by agent-guardrails/scripts/install-skill-feedback-loop.sh set -e WORKSPACE=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd) TASK_FILE="$WORKSPACE/.pending-skill-updates.txt" if [ ! -f "$TASK_FILE" ]; then echo "No pending skill updates" exit 0 fi cd "$WORKSPACE" SKILL_CHANGES=$(git status --porcelain skills/ 2>/dev/null | wc -l) if [ $SKILL_CHANGES -eq 0 ]; then echo "No uncommitted changes in skills/" exit 0 fi echo "Found $SKILL_CHANGES change(s) in skills/" git status --short skills/ echo "" # Parse task SKILL=$(grep "^Skill:" "$TASK_FILE" | head -1 | cut -d: -f2 | xargs) COMMIT=$(grep "^Commit:" "$TASK_FILE" | head -1 | cut -d: -f2 | xargs) COMMIT_MSG="Update $SKILL from enforcement improvement Auto-applied from commit $COMMIT $(grep "^Files:" "$TASK_FILE" | head -1) Semi-automatic commit (reviewed and approved by human) " echo "Commit message:" echo "---" echo "$COMMIT_MSG" echo "---" echo "" if [ "$AUTO_COMMIT_NO_CONFIRM" != "true" ]; then read -p "Commit? (y/N): " -r if [[ ! $REPLY =~ ^[Yy]$ ]]; then echo "Aborted" exit 0 fi fi git add skills/ git commit -m "$COMMIT_MSG" # Archive echo "===== $(date -u) =====" >> "$WORKSPACE/.skill-updates-archive.txt" cat "$TASK_FILE" >> "$WORKSPACE/.skill-updates-archive.txt" > "$TASK_FILE" echo "✅ Committed and archived" COMMIT_EOF chmod +x "$PROJECT_DIR/scripts/auto-commit-skill-updates.sh" echo "✅ Created scripts/auto-commit-skill-updates.sh" # 3. Install git hook mkdir -p "$PROJECT_DIR/.git/hooks" cat > "$PROJECT_DIR/.git/hooks/post-commit" << 'HOOK_EOF' #!/bin/bash cd "$(git rev-parse --show-toplevel)" bash scripts/detect-enforcement-improvement.sh HOOK_EOF chmod +x "$PROJECT_DIR/.git/hooks/post-commit" echo "✅ Installed git post-commit hook" # 4. Create workflow doc cat > "$PROJECT_DIR/SKILL-UPDATE-WORKFLOW.md" << 'DOC_EOF' # Skill Update Workflow This project has automatic skill update detection installed. ## How It Works 1. **Detection (automatic):** Git post-commit hook detects enforcement improvements 2. **Task creation (automatic):** Creates task in `.pending-skill-updates.txt` 3. **Review (manual):** You review and update skill files 4. **Commit (semi-automatic):** Script commits with confirmation ## Usage ### Check for pending tasks ```bash cat .pending-skill-updates.txt ``` ### Process an update ```bash # 1. Review task # 2. Update relevant skill files # 3. Auto-commit bash scripts/auto-commit-skill-updates.sh ``` ## Installed by agent-guardrails Part of the meta-enforcement system to ensure improvements flow back to skills. DOC_EOF echo "✅ Created SKILL-UPDATE-WORKFLOW.md" echo "" echo "==================================" echo "✅ Skill feedback loop installed!" echo "==================================" echo "" echo "What was installed:" echo " - scripts/detect-enforcement-improvement.sh" echo " - scripts/auto-commit-skill-updates.sh" echo " - .git/hooks/post-commit" echo " - SKILL-UPDATE-WORKFLOW.md" echo "" echo "Next time you commit enforcement improvements," echo "the system will auto-detect and remind you to update skills." ```` ## File: scripts/install.sh size: 3460 sha: a1d848b35a86357d9fe707d2cbfe02b72d3ffa43 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/scripts/install.sh ```text #!/bin/bash # install.sh — One-click setup for agent-guardrails in a project # Usage: bash install.sh [project_directory] # Installs: git pre-commit hook, check scripts, registry template set -euo pipefail SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)" PROJECT_DIR="${1:-.}" if [ ! -d "$PROJECT_DIR" ]; then echo "❌ Directory not found: $PROJECT_DIR" echo "Usage: bash install.sh [project_directory]" exit 1 fi PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)" echo "╔══════════════════════════════════════════════════╗" echo "║ Agent Guardrails — Install ║" echo "╚══════════════════════════════════════════════════╝" echo " Project: $PROJECT_DIR" echo " Skill: $SKILL_DIR" echo "" # 1. Copy check scripts echo "📋 Installing check scripts..." mkdir -p "$PROJECT_DIR/scripts" cp "$SKILL_DIR/scripts/pre-create-check.sh" "$PROJECT_DIR/scripts/" cp "$SKILL_DIR/scripts/post-create-validate.sh" "$PROJECT_DIR/scripts/" cp "$SKILL_DIR/scripts/check-secrets.sh" "$PROJECT_DIR/scripts/" chmod +x "$PROJECT_DIR/scripts/pre-create-check.sh" chmod +x "$PROJECT_DIR/scripts/post-create-validate.sh" chmod +x "$PROJECT_DIR/scripts/check-secrets.sh" echo " ✅ Copied to $PROJECT_DIR/scripts/" # 2. Install git pre-commit hook (if git repo) if [ -d "$PROJECT_DIR/.git" ]; then echo "" echo "🔗 Installing git pre-commit hook..." HOOKS_DIR="$PROJECT_DIR/.git/hooks" mkdir -p "$HOOKS_DIR" if [ -f "$HOOKS_DIR/pre-commit" ]; then echo " ⚠️ Existing pre-commit hook found — backing up to pre-commit.bak" cp "$HOOKS_DIR/pre-commit" "$HOOKS_DIR/pre-commit.bak" fi cp "$SKILL_DIR/assets/pre-commit-hook" "$HOOKS_DIR/pre-commit" chmod +x "$HOOKS_DIR/pre-commit" echo " ✅ Pre-commit hook installed" else echo "" echo "ℹ️ Not a git repo — skipping pre-commit hook" fi # 3. Create registry template if no __init__.py exists if [ ! -f "$PROJECT_DIR/__init__.py" ]; then echo "" echo "📦 Creating module registry template..." cp "$SKILL_DIR/assets/registry-template.py" "$PROJECT_DIR/__init__.py" echo " ✅ Created $PROJECT_DIR/__init__.py (edit to list your modules)" else echo "" echo "ℹ️ __init__.py already exists — skipping registry template" fi echo "" echo "╔══════════════════════════════════════════════════╗" echo "║ ✅ Installation complete! ║" echo "╠══════════════════════════════════════════════════╣" echo "║ Before new .py files: ║" echo "║ bash scripts/pre-create-check.sh . ║" echo "║ After editing .py files: ║" echo "║ bash scripts/post-create-validate.sh ║" echo "║ Scan for secrets: ║" echo "║ bash scripts/check-secrets.sh . ║" echo "╚══════════════════════════════════════════════════╝" ``` ## File: scripts/post-create-validate.sh size: 4766 sha: 444e3ebda1e682cdfa5bd9c342d456022ad3ba59 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/scripts/post-create-validate.sh ```text #!/bin/bash # post-create-validate.sh — Run AFTER creating/editing a Python file # Checks for function duplication, missing imports, and bypass patterns. # Usage: bash post-create-validate.sh set -euo pipefail NEW_FILE="${1:-}" if [ -z "$NEW_FILE" ] || [ ! -f "$NEW_FILE" ]; then echo "❌ File not found: $NEW_FILE" echo "Usage: bash post-create-validate.sh " exit 1 fi PROJECT_DIR=$(dirname "$NEW_FILE") NEW_BASENAME=$(basename "$NEW_FILE") WARNINGS=0 echo "╔══════════════════════════════════════════════════╗" echo "║ POST-CREATION VALIDATION ║" echo "╚══════════════════════════════════════════════════╝" echo " File: $NEW_FILE" echo "" # 1. Extract function names from new file NEW_FUNCS=$(grep "^def " "$NEW_FILE" 2>/dev/null | sed 's/def \([a-zA-Z_]*\).*/\1/' || true) if [ -z "$NEW_FUNCS" ]; then echo "ℹ️ No function definitions found in new file." else # 2. Check for duplicate function names in other project files echo "🔍 Checking for function duplication..." echo "─────────────────────────────────────" for func_name in $NEW_FUNCS; do EXISTING=$(grep -rn "^def ${func_name}\b" "$PROJECT_DIR"/*.py 2>/dev/null | grep -v "$NEW_BASENAME" || true) if [ -n "$EXISTING" ]; then echo " ⚠️ DUPLICATE: '$func_name' already exists!" echo " $EXISTING" WARNINGS=$((WARNINGS + 1)) fi done if [ "$WARNINGS" -eq 0 ]; then echo " ✅ No duplicate functions found." fi echo "" fi # 3. Check if new file imports from established modules echo "🔗 Checking imports from established modules..." echo "─────────────────────────────────────────────" # Find established modules (files with >5 functions = likely a core module) ESTABLISHED="" for pyfile in "$PROJECT_DIR"/*.py; do [ "$pyfile" = "$NEW_FILE" ] && continue [ ! -f "$pyfile" ] && continue func_count=$(grep -c "^def " "$pyfile" 2>/dev/null || true) func_count=${func_count:-0} func_count=$(echo "$func_count" | tr -d '[:space:]') if [ "$func_count" -gt 5 ]; then mod_name=$(basename "$pyfile" .py) ESTABLISHED="$ESTABLISHED $mod_name" fi done if [ -n "$ESTABLISHED" ]; then IMPORTS_FOUND=0 for mod in $ESTABLISHED; do if grep -q "from ${mod}\|import ${mod}\|from \.${mod}" "$NEW_FILE" 2>/dev/null; then echo " ✅ Imports from established module: $mod" IMPORTS_FOUND=1 fi done if [ "$IMPORTS_FOUND" -eq 0 ]; then echo " ⚠️ WARNING: Does not import from any established module!" echo " Established modules:$ESTABLISHED" echo " Consider importing validated functions instead of reimplementing." WARNINGS=$((WARNINGS + 1)) fi else echo " ℹ️ No established modules (>5 functions) found in project." fi echo "" # 4. Check for bypass patterns echo "🚫 Checking for bypass patterns..." echo "──────────────────────────────────" BYPASS_PATTERNS=("simplified version" "quick version" "temporary" "TODO: integrate" "hack" "workaround") for pattern in "${BYPASS_PATTERNS[@]}"; do MATCH=$(grep -in "$pattern" "$NEW_FILE" 2>/dev/null || true) if [ -n "$MATCH" ]; then echo " ⚠️ BYPASS PATTERN: '$pattern'" echo " $MATCH" WARNINGS=$((WARNINGS + 1)) fi done echo "" # 5. Summary if [ "$WARNINGS" -gt 0 ]; then echo "╔══════════════════════════════════════════════════╗" echo "║ ⚠️ $WARNINGS WARNING(S) — Review before proceeding ║" echo "╚══════════════════════════════════════════════════╝" exit 1 else echo "╔══════════════════════════════════════════════════╗" echo "║ ✅ All checks passed ║" echo "╚══════════════════════════════════════════════════╝" exit 0 fi ``` ## File: scripts/pre-create-check.sh size: 3658 sha: 9e61e818e9414ff3c10858e026a91bccdae51d68 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/scripts/pre-create-check.sh ```text #!/bin/bash # pre-create-check.sh — Run BEFORE creating any new Python file in a project # Lists existing modules and functions so agents can import instead of rewrite. # Usage: bash pre-create-check.sh [project_directory] set -euo pipefail PROJECT_DIR="${1:-.}" if [ ! -d "$PROJECT_DIR" ]; then echo "❌ Directory not found: $PROJECT_DIR" exit 1 fi echo "╔══════════════════════════════════════════════════╗" echo "║ PRE-CREATION CHECK ║" echo "╚══════════════════════════════════════════════════╝" echo "" # 1. List existing Python modules echo "📦 Existing Python modules:" echo "─────────────────────────────" find "$PROJECT_DIR" -maxdepth 2 -name "*.py" -not -path "*/__pycache__/*" -not -path "*/.git/*" | sort | while read -r f; do funcs=$(grep -c "^def " "$f" 2>/dev/null || true) funcs=${funcs:-0} funcs=$(echo "$funcs" | tr -d '[:space:]') echo " $(basename "$f") ($funcs functions)" done echo "" # 2. List validation/scoring/analysis functions echo "🔍 Validation / Scoring / Analysis functions:" echo "─────────────────────────────────────────────" FOUND_VALIDATION=$(grep -rn "^def \(validate\|score\|analyze\|check\|verify\|assess\|evaluate\|fetch\|generate_report\)" "$PROJECT_DIR"/*.py 2>/dev/null || true) if [ -n "$FOUND_VALIDATION" ]; then echo "$FOUND_VALIDATION" | sed 's|^.*/||' | while IFS=: read -r file line func; do echo " $file:$line → $func" done else echo " (none found)" fi echo "" # 3. List ALL public functions for import reference echo "📋 All public functions available for import:" echo "─────────────────────────────────────────────" FOUND_PUBLIC=$(grep -rn "^def [a-z]" "$PROJECT_DIR"/*.py 2>/dev/null || true) if [ -n "$FOUND_PUBLIC" ]; then echo "$FOUND_PUBLIC" | sed 's|^.*/||' | while IFS=: read -r file line func; do func_name=$(echo "$func" | sed 's/def \([a-zA-Z_]*\).*/\1/') echo " from $(basename "$file" .py) import $func_name # $file:$line" done else echo " (none found)" fi echo "" # 4. Show SKILL.md / STATUS.md if present for doc in SKILL.md STATUS.md; do if [ -f "$PROJECT_DIR/$doc" ]; then echo "📖 $doc summary:" echo "─────────────────────" head -40 "$PROJECT_DIR/$doc" echo "" echo " ... (read full $doc for details)" echo "" fi done # 5. Show __init__.py registry if it exists if [ -f "$PROJECT_DIR/__init__.py" ]; then echo "📦 Official module registry (__init__.py):" echo "─────────────────────────────────────────" cat "$PROJECT_DIR/__init__.py" echo "" fi echo "╔══════════════════════════════════════════════════╗" echo "║ ⚠️ IMPORT existing modules, don't rewrite! ║" echo "║ Check above list. If it exists, USE it. ║" echo "╚══════════════════════════════════════════════════╝" ``` ## File: references/agents-md-template.md size: 1639 sha: 4f767a85b75039a39d9f74795d959b541c285900 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/references/agents-md-template.md ````text # AGENTS.md — Template with Mechanical Enforcement Copy and adapt this template for your project's AGENTS.md file. --- # AGENTS.md — [Project Name] ## 🚨 Iron Laws ### 1. Never Hardcode Secrets - All secrets from environment variables — no exceptions - No fallback values in `os.getenv()` — fail loudly - Pre-commit scan: `bash scripts/check-secrets.sh` ### 2. Never Bypass Established Standards - Existing validation logic → **import it, don't rewrite** - "Too slow" → **optimize it, don't bypass it** - Before new code → check if project already has it - User-facing output → must go through project's validation pipeline ### 3. Verify Before Acting - Modify config → backup first, verify after - Write code → research first, test after - Uncertain → look it up, don't guess ## 🔧 Mechanical Enforcement **Rules in markdown are suggestions. Code hooks are laws.** ### Before creating any new .py file: ```bash bash scripts/pre-create-check.sh . ``` ### After creating/editing any .py file: ```bash bash scripts/post-create-validate.sh ``` ### Git pre-commit hook (automatic): - Blocks bypass patterns ("simplified version", "quick version", "temporary") - Blocks hardcoded secrets - Override with `--no-verify` (explain why) ### Project registry: - `__init__.py` lists official validated functions - New scripts MUST import from registry, not reimplement ### Self-check before writing code: - [ ] Does existing code already do what I need? - [ ] Am I "simplifying" away important validation? - [ ] Does output go through the validated pipeline? - [ ] Am I importing from the registry? ```` ## File: references/deployment-verification-guide.md size: 7079 sha: d5fbb270b2d34a7dada6ac4f54d43ab82b5e8faa upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/references/deployment-verification-guide.md ````text # Deployment Verification Guide **Core Problem:** Agents build features but forget to wire them into production. **Real Example (2026-02-02):** - Built: `dynamic_trader.py` with news verification - Built: Improved `notify.py` with URLs and scoring - **Forgot:** Hourly cron still using old output format - **Result:** Users got incomplete reports --- ## Why This Happens **Agent mindset:** ``` Task: "Build feature X" → Code written ✅ → "Done" ❌ (Wrong!) ``` **Should be:** ``` Goal: "Users receive benefit X" → Build feature → Test production flow → Find integration gaps → Fix them → Verify user receives benefit → "Done" ✅ ``` --- ## The Gap: Code vs Production **What agents often miss:** 1. **Entry points** - How does code actually run? - Cron jobs - APIs/webhooks - Manual commands - Background workers 2. **Data flow** - Where does output go? - Files - Databases - Message queues - User-facing channels 3. **Format assumptions** - What does consumer expect? - JSON vs plain text - Field names/structure - Required vs optional fields --- ## Mechanical Enforcement **Don't rely on agent memory. Make it mechanical.** ### 1. Deployment Check Script Template: `scripts/create-deployment-check.sh` Creates `.deployment-check.sh` that: - ✅ Runs actual production flow - ✅ Verifies output exists - ✅ Checks output format - ✅ Tests all integration points - ❌ Blocks if any test fails ### 2. Pre-Commit Hook Runs deployment check before allowing commit: ```bash # Project files changed? → Run .deployment-check.sh → All pass? Allow commit → Any fail? Block ❌ ``` ### 3. Deployment Checklist Template: `DEPLOYMENT-CHECKLIST.md` Forces agent to think through: - What are the entry points? - Where does output go? - What format is expected? - How will I verify end-to-end? --- ## Implementation Steps ### For a New Project ```bash cd your-project/ bash /path/to/agent-guardrails/scripts/create-deployment-check.sh . ``` This creates: - `.deployment-check.sh` (customize with your tests) - `DEPLOYMENT-CHECKLIST.md` (document your flow) - `.git-hooks/pre-commit-deployment` (install to enforce) ### For Existing Project 1. **Identify integration points:** - Where does your code get called? - What consumes your output? 2. **Create tests:** ```bash # Test: Does main flow work? bash scripts/generate_report.sh # Test: Output has required fields? grep -q "Required Field" /tmp/output.txt # Test: User actually receives it? # (manual check or automated) ``` 3. **Add to .deployment-check.sh:** ```bash echo "Test 1: Report generation..." if bash scripts/generate_report.sh > /dev/null 2>&1; then echo " ✅ Generated" else echo " ❌ Failed" FAILED=1 fi ``` 4. **Install git hook:** ```bash cp .git-hooks/pre-commit-deployment .git/hooks/pre-commit chmod +x .git/hooks/pre-commit ``` --- ## Test Coverage ### Minimum (Must Have) - ✅ **Main flow runs** (no crashes) - ✅ **Output exists** (file/DB/message created) - ✅ **Output format valid** (parseable, has required fields) ### Recommended (Should Have) - ✅ **All entry points tested** (cron, API, manual) - ✅ **Edge cases handled** (empty, errors, timeouts) - ✅ **User-facing output verified** (what they actually see) ### Advanced (Nice to Have) - ✅ **Integration tests** (end-to-end with real services) - ✅ **Performance checks** (not too slow) - ✅ **Monitoring alerts** (catch issues in production) --- ## Common Pitfalls ### 1. "I tested the function" ❌ **Wrong:** ```python def generate_report(): return "Report" # Tested: ✅ Returns "Report" ``` ✅ **Right:** ```bash # Test the FULL FLOW: bash scripts/hourly_cron.sh # → Calls generate_report() # → Saves to /tmp/report.txt # → Sends via message tool # → User receives message # Verify: User got "Report" in their chat ``` ### 2. "It works when I run it manually" ❌ **Wrong:** ```bash # Agent runs: python3 script.py # Works! ✅ # But cron runs: /usr/bin/python3 script.py # Different environment, missing deps ❌ ``` ✅ **Right:** ```bash # Test the ACTUAL cron command: /usr/bin/python3 /full/path/script.py # Or better: run the cron job manually bash /path/to/cron_wrapper.sh ``` ### 3. "I updated the code" ❌ **Wrong:** ```bash # Updated: notify.py # But cron still calls: old_notify.py # Users get old output ❌ ``` ✅ **Right:** ```bash # Check what cron ACTUALLY calls: crontab -l | grep notify # Update ALL entry points: # - Cron jobs # - API routes # - Manual commands # - Documentation ``` --- ## Integration with Agent Workflow ### Update AGENTS.md Add to your project's `AGENTS.md`: ```markdown ### Deployment Verification (Mandatory) **Before marking feature "done":** ```bash bash .deployment-check.sh ``` **Git hook:** Auto-runs on commit. Blocks if fails. **Rule:** Feature ≠ done until user receives benefit from production flow. ``` ### Agent Instruction ```markdown ## Completing Features When you finish a feature: 1. ✅ Code written 2. ✅ **Run .deployment-check.sh** ← Mandatory 3. ✅ **Fix any issues found** 4. ✅ **Re-verify** 5. ✅ **Update DEPLOYMENT-CHECKLIST.md** with any new lessons Only then say "Done." ``` --- ## Example: Kalshi Hourly Reports ### Problem Built new notify.py with scoring/URLs, but forgot to update cron. ### Solution **Created .deployment-check.sh:** ```bash # Test 1: Cron generates report bash kalshi/send_hourly_scan.sh > /dev/null 2>&1 if [ -f /tmp/kalshi_hourly_scan_dm.txt ]; then echo " ✅ Report generated" fi # Test 2: Report has URLs if grep -q "https://kalshi.com/" /tmp/kalshi_hourly_scan_dm.txt; then echo " ✅ URLs present" fi # Test 3: Report has scoring if grep -q "Score:" /tmp/kalshi_hourly_scan_dm.txt; then echo " ✅ Scoring present" fi ``` **Installed git hook:** ```bash # Runs .deployment-check.sh on every commit # Blocks if report missing URLs/scoring ``` **Result:** - Can't commit without verification passing - Catches integration gaps before they reach users --- ## Maintenance ### When to Update Update `.deployment-check.sh` when: - Adding new features - Changing output format - Adding new entry points - Integrating new services ### Record Lessons In `DEPLOYMENT-CHECKLIST.md`: ```markdown ## Lessons Learned ### 2026-02-02: Incomplete Hourly Reports **Symptom:** Users got reports missing URLs **Root cause:** Updated notify.py but cron still used old format **Fix:** Verified cron output matches new format **Prevention:** Added "check cron output" to .deployment-check.sh ``` --- ## Summary **Problem:** Agents build features but don't verify production integration **Solution:** Mechanical enforcement via deployment checks + git hooks **Key Principle:** A feature isn't done until users receive the benefit **Reliability:** Code hooks (100%) > Prompt rules (60-70%) > Markdown (40-50%) **Remember:** If it's not mechanically enforced, it will be forgotten. ```` ## File: references/enforcement-research.md size: 3738 sha: 21c2628335b5f3117670791a66e6f44a5d91316f upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/references/enforcement-research.md ```text # AI Agent Rules Enforcement Research ## TL;DR **Prompts are advisory, code is mandatory.** You cannot rely on instructions alone to enforce standards. You need mechanical enforcement layers that run regardless of what the LLM decides to do. ## Enforcement Reliability Hierarchy 1. **Code-level enforcement** (hooks, pre-commit, linters) — 100% reliable 2. **Structural constraints** (API design, imports, module boundaries) — 95% reliable 3. **Self-verification loops** (agent checks own work) — 80% reliable 4. **Prompt instructions** (AGENTS.md, system prompts) — 60-70% reliable 5. **Written rules in markdown** — 40-50% reliable (degrades with context length) ## Key Findings ### Code Hooks Are the Gold Standard IDE and agent frameworks support **hooks** — shell scripts that run at specific lifecycle points. These are deterministic, not advisory. > "Unlike AGENTS.md instructions which are advisory, hooks are deterministic and guarantee the action happens." **Hook lifecycle points:** - **Pre-tool-use** — runs before a tool call, can block it - **Post-tool-use** — runs after file edits, can reject changes - **Pre-commit** — runs before git commits, can block them - **Session start** — inject context at beginning of sessions ### Why Markdown Rules Degrade From Anthropic's best practices: > "If the agent keeps doing something you don't want despite having a rule against it, the file is probably too long and the rule is getting lost." As context windows fill up, earlier instructions lose influence. Rules at the beginning of a long conversation have less effect than rules enforced mechanically at each step. ### Architectural Constraints Design code so bypassing is structurally difficult: - **Module registries** (`__init__.py`) that export all public functions - **Import enforcement** — new scripts must import from registries - **Single source of truth** — one implementation per function - **Pipeline architecture** — data must flow through validated stages ### Self-Verification Loops Have the agent self-check before finalizing: 1. Does this project have existing modules? (Check `__init__.py`) 2. Are there existing functions that do what I need? 3. Am I importing them or rewriting them? 4. If rewriting, why? Document the reason. ### Multi-Agent Patterns Research from scaling autonomous agents: - **Planner-worker separation** — plan specifies which modules to use, worker executes - **Judge agents** — separate agent verifies compliance - **Fresh starts combat drift** — long conversations cause agents to lose focus - **Model choice affects compliance** — some models take more shortcuts than others ## Practical Implementation Tiers ### Tier 1: Immediate - Pre-creation checklist script (run before new files) - Post-creation validator (run after new files) - Git pre-commit hook (block bypass patterns and secrets) ### Tier 2: Short-term - Project-level import registries (`__init__.py`) - Automated integration tests verifying import compliance ### Tier 3: Medium-term - Self-review loops for all agent outputs - Architectural constraints making bypassing structurally hard - Automated evals detecting standard-bypass patterns ## Key Principle > Don't add more markdown rules. Add mechanical enforcement. > Rules in markdown are suggestions. Hooks, tests, and architectural constraints are laws. ## Sources 1. Cursor Blog — Agent best practices, hooks, scaling research 2. Anthropic — Claude Code best practices, hooks guide 3. Guardrails AI — Framework with 67+ validators 4. NVIDIA NeMo Guardrails — Open-source toolkit (5 rail types) 5. Constitutional AI — Self-critique and revision patterns 6. OpenAI — Prompt engineering guide ``` ## File: references/skill-update-feedback.md size: 5122 sha: 61ee4f09bfdae49b0e66f2e39d00d05cf27b1a37 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/references/skill-update-feedback.md ````text # Skill Update Feedback Loop - Meta Enforcement **The Meta-Problem:** Enforcement improvements don't automatically flow back to skills. **Example:** 1. Project A builds `.deployment-check.sh` to prevent deployment gaps 2. Works great in Project A 3. **Gap:** Project B, C, D don't know about it 4. **Root cause:** Improvement stayed in Project A, didn't flow back to shared skill **The Loop:** ``` Project improvement → [Manual remember?] → Update skill → Other projects benefit ↑ Often breaks here ``` --- ## Solution: Automatic Feedback Loop **Make it impossible to forget:** ``` Project improvement → [Auto-detect] → Create task → [Semi-auto commit] → Skill updated ↓ No memory required ``` **Components:** 1. **Git post-commit hook** - Runs after every commit 2. **detect-enforcement-improvement.sh** - Scans for enforcement patterns 3. **auto-commit-skill-updates.sh** - Semi-automatic commit with confirmation 4. **.pending-skill-updates.txt** - Task queue --- ## How It Works ### Phase 1: Detection (Automatic) **Trigger:** Every `git commit` **Process:** ```bash commit → .git/hooks/post-commit → scripts/detect-enforcement-improvement.sh → Scans changed files for patterns: - *.deployment-check.sh - *DEPLOYMENT-CHECKLIST.md - *pre-commit*, *post-create* - *enforcement*, *guardrails* → If found → Creates task in .pending-skill-updates.txt ``` **Task format:** ``` --- Date: 2026-02-02 21:45 UTC Commit: abc123 Skill: agent-guardrails Files: project/.deployment-check.sh Action needed: 1. Review improvement 2. Extract reusable parts 3. Update skills/agent-guardrails/ 4. Commit --- ``` ### Phase 2: Update (Manual) **Human does:** 1. Reviews the improvement 2. Extracts reusable patterns/scripts 3. Updates skill files (scripts/, references/, SKILL.md) 4. Tests if needed **Why manual:** - Judgment needed on what's reusable - Some improvements are project-specific - Quality control ### Phase 3: Commit (Semi-Automatic) **Human runs:** ```bash bash scripts/auto-commit-skill-updates.sh ``` **Script does:** 1. Checks for uncommitted changes in `skills/` 2. Parses `.pending-skill-updates.txt` to get context 3. Generates commit message automatically 4. **Asks for confirmation** (y/N) 5. Commits if approved 6. Archives task 7. Clears pending tasks file **Safety:** - ✅ Shows what will be committed - ✅ Confirmation step - ✅ Auto-generated commit message includes context - ✅ Can abort safely --- ## Installation ### In a Project ```bash cd your-project/ bash /path/to/agent-guardrails/scripts/install-skill-feedback-loop.sh . ``` This installs: - Detection script - Auto-commit script - Git post-commit hook - Workflow documentation ### In Agent Guardrails Itself Same process - the system is self-hosting: ```bash cd agent-guardrails/ bash scripts/install-skill-feedback-loop.sh . ``` **Bootstrapping note:** First installation needs manual setup since the system doesn't exist yet. --- ## Maintenance ### Check Pending Tasks ```bash cat .pending-skill-updates.txt ``` ### View Archive ```bash cat .skill-updates-archive.txt ``` ### Update Detection Patterns Edit `scripts/detect-enforcement-improvement.sh`: ```bash ENFORCEMENT_PATTERNS=( "\.deployment-check\.sh" "your-new-pattern" ) ``` --- ## Benefits **Without feedback loop:** - ❌ Improvements stay siloed - ❌ Rely on human memory - ❌ Skills become stale - ❌ Knowledge doesn't compound **With feedback loop:** - ✅ Can't forget (mechanical reminder) - ✅ Improvements automatically tracked - ✅ Skills stay current - ✅ Knowledge compounds across projects --- ## Dogfooding **This system was built to solve its own problem:** 1. We built deployment verification (project-level) 2. Almost forgot to update agent-guardrails 3. User pointed out the gap 4. We built automatic feedback loop 5. **The feedback loop itself needed to be added to agent-guardrails** 6. Bootstrapping: Manual first time, automatic after **Meta-meta note:** If we improve this feedback loop, the loop will detect its own improvement! --- ## Future Enhancements ### Phase 4: Fully Automatic (Vision) Replace manual Phase 2 with AI: ```bash # AI agent does: 1. Reads pending task 2. Analyzes changed files 3. Extracts reusable patterns automatically 4. Generates skill updates 5. Runs tests 6. If tests pass → Auto-commits 7. If tests fail → Creates manual review task ``` **Requirements:** - AI capable of code analysis and generation - Comprehensive test suite for skills - Safety rails for review --- ## TL;DR **Problem:** Enforcement improvements don't flow back to skills → knowledge siloed **Solution:** Automatic detection + semi-automatic commit → can't forget **How:** Git hook detects → Creates task → Human updates → Script commits **Result:** Every improvement becomes reusable knowledge **This is meta-enforcement:** Enforcing that enforcement improvements are preserved and shared. ```` ## File: references/SKILL_CN.md size: 5206 sha: e11bb0b0bf7c159c9e69fffed767aa6030eba799 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/references/SKILL_CN.md ````text # Agent Guardrails 🛡️ — 中文文档 ## 你的AI助手在偷偷绕过你的规则，这个工具用代码来阻止它。 **适用于：** Claude Code | Clawdbot | Cursor | 任何AI编程助手 > Markdown里的规则只是建议。代码钩子才是法律。 🚨 **在生产事故发生之前就阻止它** — 这套工具诞生于真实的服务器崩溃、密钥泄露和静默绕过 --- ## 问题是什么？ 你花了几个小时搭建验证流程、评分系统和校验逻辑。然后你的AI助手写了一个"简化版"，把这些全部绕过了。听起来熟悉吗？ ### 真实生产事故（2026年2月） **🔥 服务器崩溃：** 错误的配置修改 → 服务崩溃循环 → 宕机一整晚 **🔑 密钥泄露：** Notion token硬编码在代码里，差点推送到公开GitHub **🔄 代码重写：** AI重写了已验证的评分逻辑而不是导入它，发送了未验证的预测 **🚀 部署遗漏：** 新功能做好了但忘了接入生产环境，用户收到不完整的输出 这不是提示词的问题——这是**执行力**的问题。写再多markdown规则也没用。你需要**真正有效的**机械化强制执行。 --- ## 执行可靠性层级 | 层级 | 方法 | 可靠性 | |------|------|--------| | 1 | **代码钩子**（pre-commit、创建前/后检查） | 100% | | 2 | **架构约束**（导入注册表、强制复用） | 95% | | 3 | **自我验证循环** | 80% | | 4 | **提示规则**（AGENTS.md） | 60-70% | | 5 | **Markdown文档** | 40-50% ⚠️ | 本工具专注于第1-2层：**真正管用的那些**。 --- ## 包含什么？ | 工具 | 用途 | |------|------| | `scripts/install.sh` | 一键安装到你的项目 | | `scripts/pre-create-check.sh` | 创建新文件前列出已有模块，防止重复造轮子 | | `scripts/post-create-validate.sh` | 检测重复函数和缺失的导入 | | `scripts/check-secrets.sh` | 扫描硬编码的token/密钥/密码 | | `scripts/create-deployment-check.sh` | 生成部署验证脚本和检查清单 | | `scripts/install-skill-feedback-loop.sh` | 设置skill更新自动检测和反馈循环 | | `assets/pre-commit-hook` | Git钩子：自动拦截绕过模式 + 密钥泄露 | | `assets/registry-template.py` | `__init__.py`模板，强制导入已验证函数 | | `references/agents-md-template.md` | 经过实战检验的AGENTS.md模板 | | `references/enforcement-research.md` | 完整研究：为什么代码 > 提示词 | --- ## 快速开始 **Claude Code 用户：** ```bash git clone https://github.com/jzOcb/agent-guardrails ~/.claude/skills/agent-guardrails cd 你的项目 && bash ~/.claude/skills/agent-guardrails/scripts/install.sh . ``` **Clawdbot 用户：** ```bash clawdhub install agent-guardrails ``` **手动安装：** ```bash bash /path/to/agent-guardrails/scripts/install.sh /path/to/your/project ``` 安装后自动完成： - ✅ 安装git pre-commit钩子（拦截绕过模式 + 硬编码密钥） - ✅ 创建`__init__.py`注册表模板 - ✅ 复制检查脚本到你的项目 - ✅ 在你的AGENTS.md中添加执行规则 --- ## 使用方法 ### 创建新文件之前： ```bash bash scripts/pre-create-check.sh /path/to/project ``` 显示已有的模块和函数。如果已经有了——**直接导入，不要重写**。 ### 创建/编辑文件之后： ```bash bash scripts/post-create-validate.sh /path/to/new_file.py ``` 捕获重复函数、缺失导入、以及"简化版"/"临时"等绕过模式。 ### 密钥扫描： ```bash bash scripts/check-secrets.sh /path/to/project ``` --- ## 工作原理 ### Pre-commit 钩子 自动拦截包含以下内容的提交： - **绕过模式**：`"simplified version"`, `"quick version"`, `"temporary"`, `"TODO: integrate"` - **硬编码密钥**：源代码中的API key、token、password ### 导入注册表 每个项目有一个`__init__.py`明确列出已验证的函数： ```python # 这是本项目唯一认可的接口 from .core import validate_data, score_item, generate_report # 新脚本必须从这里导入，不许重新实现 ``` --- ## 诞生故事 这套工具诞生于一个真实事故（2026-02-02）：我们为预测市场分析搭建了一套完整的决策引擎——评分系统、规则解析器、新闻验证、数据源校验。然后AI助手创建了一个"快速扫描"脚本，把**所有这些**全部绕过了，发送了未经验证的推荐。 修复方法不是写更多规则。而是写代码来**机械化阻止**这种绕过。 --- ## 核心原则 > 不要添加更多markdown规则。添加机械化执行。 > 如果AI持续绕过某个标准，不要写更强的规则——写一个**阻止它的钩子**。 --- ## 开源协议 MIT — 随便用，随便分享，让你的AI助手听话。 **GitHub:** https://github.com/jzOcb/agent-guardrails **英文文档:** [README.md](../README.md) ## 相关项目 - [config-guard](https://github.com/jzOcb/config-guard) — 防止 AI 改错 OpenClaw 配置导致网关崩溃（自动备份、schema 验证、自动回滚） - [upgrade-guard](https://github.com/jzOcb/upgrade-guard) — 安全升级 OpenClaw：快照、验证、自动回滚、OS 级 watchdog ```` ## File: assets/init-registry-template.py size: 1231 sha: 0879e7f86cb8f0903157d1441d25e0c57b872058 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/assets/init-registry-template.py ```text """ Project Module Registry ======================= These are the VALIDATED, ESTABLISHED functions for this project. Any new script MUST import from here. Do NOT reimplement. Usage: from project_name import function_a, function_b Instructions: 1. Replace 'project_name' with your actual project/package name 2. Replace the example imports below with your real modules 3. List ALL public functions that other scripts should use 4. Add comments explaining what each module provides """ # === Core Module (your primary validated module) === # from .core_module import ( # validate_data, # Validate input data # process_item, # Core processing function # generate_report, # Generate output report # ) # === Data Sources === # from .data_sources import ( # fetch_data, # Fetch data from external source # parse_response, # Parse API responses # ) # === RULES === # 1. Functions listed here are the ONLY approved implementations # 2. New scripts that need this functionality MUST import from here # 3. If you need new functionality, EXTEND existing modules, don't create parallel versions # 4. "Quick" or "simplified" reimplementations are NOT acceptable ``` ## File: assets/pre-commit-hook size: 2740 sha: 118ce2d3a4784d81763143fefe1efe8fd08cc0f7 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/assets/pre-commit-hook ```text #!/bin/bash # Git pre-commit hook — Mechanical enforcement of project standards # Blocks bypass patterns and hardcoded secrets in staged changes. # Install: cp this file to .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit set -euo pipefail ERRORS=0 STAGED_DIFF=$(git diff --cached --diff-filter=ACM) # 1. Check for bypass patterns in staged changes echo "🔍 Checking for bypass patterns..." BYPASS_PATTERNS=( "simplified version" "quick version" "temporary" "TODO: integrate" "# hack" "# workaround" "skip validation" "bypass" ) for pattern in "${BYPASS_PATTERNS[@]}"; do if echo "$STAGED_DIFF" | grep -i "+.*$pattern" > /dev/null 2>&1; then echo " ⚠️ BLOCKED: Found bypass pattern '$pattern' in staged changes" echo "$STAGED_DIFF" | grep -in "+.*$pattern" | head -3 ERRORS=$((ERRORS + 1)) fi done # 2. Check for hardcoded secrets echo "🔐 Checking for hardcoded secrets..." SECRET_PATTERNS=( 'token\s*=\s*["\x27][A-Za-z0-9_\-]{20,}' 'api_key\s*=\s*["\x27][A-Za-z0-9_\-]{20,}' 'secret\s*=\s*["\x27][A-Za-z0-9_\-]{20,}' 'password\s*=\s*["\x27][^\x27"]{8,}' 'Bearer [A-Za-z0-9_\-]{20,}' 'sk-[A-Za-z0-9]{20,}' 'ghp_[A-Za-z0-9]{20,}' 'xoxb-[A-Za-z0-9\-]{20,}' 'AKIA[0-9A-Z]{16}' ) for pattern in "${SECRET_PATTERNS[@]}"; do if echo "$STAGED_DIFF" | grep -P "+.*$pattern" > /dev/null 2>&1; then echo " 🚨 BLOCKED: Possible hardcoded secret detected!" echo " Pattern: $pattern" ERRORS=$((ERRORS + 1)) fi done # 3. Check staged Python files for os.getenv with default values STAGED_PY=$(git diff --cached --name-only --diff-filter=ACM | grep '\.py$' || true) if [ -n "$STAGED_PY" ]; then echo "🐍 Checking Python files for secret defaults..." for pyfile in $STAGED_PY; do if git show ":$pyfile" 2>/dev/null | grep -n 'os\.getenv.*,.*["\x27]' | grep -iv 'default\|localhost\|http\|utf' > /dev/null 2>&1; then echo " ⚠️ WARNING: $pyfile may have os.getenv() with fallback secret values" ERRORS=$((ERRORS + 1)) fi done fi # Result if [ "$ERRORS" -gt 0 ]; then echo "" echo "╔══════════════════════════════════════════════════╗" echo "║ ❌ COMMIT BLOCKED — $ERRORS issue(s) found ║" echo "║ Fix issues or use --no-verify to override ║" echo "╚══════════════════════════════════════════════════╝" exit 1 else echo "✅ Pre-commit checks passed." exit 0 fi ``` ## File: assets/registry-template.py size: 1572 sha: e2e5cf9c9b59e4a8e2f3107b15f442860c6e1791 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/assets/registry-template.py ```text """ Project Name — Official Module Registry ======================================== These are the VALIDATED, ESTABLISHED functions for this project. Any new script MUST import from here. Do NOT reimplement. Usage: from project_name import function_a, function_b Instructions: 1. Replace 'project_name' with your actual project/package name 2. Replace the example imports below with your real modules and functions 3. Update the module reference section 4. New scripts must import from this registry, not reimplement """ # === Core Module (your_core_module.py) === # Uncomment and edit these imports to match your project: # # from .your_core_module import ( # validate_data, # Validate input data # process_data, # Main data processing pipeline # generate_report, # Generate output report # ) # === Utility Module (utils.py) === # from .utils import ( # fetch_data, # Fetch data from external sources # format_output, # Format output for display # ) # === What each module does (for reference) === # your_core_module.py — Core logic: validation, processing, reporting # utils.py — Shared utilities: data fetching, formatting # config.py — Configuration management # === RULES === # 1. Functions listed above are the ONLY approved implementations # 2. New scripts that need these capabilities MUST import, not reimplement # 3. If you need new functionality, EXTEND existing modules first # 4. Don't create parallel versions of existing validated functions ``` ## File: .gitignore size: 20 sha: 7aaee7cbdce359c09cc5467b53a12cc41d6cab59 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/.gitignore ```text LISTING-STRATEGY.md ``` ## File: CHANGELOG.md size: 4034 sha: 1633353dcecc90f947fc24f4181c27a15889f8bb upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/CHANGELOG.md ````text # Changelog All notable changes to Agent Guardrails will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [1.1.0] - 2026-02-02 ### Added - **Deployment Verification System** - Prevents "code complete but not wired to production" failures - `create-deployment-check.sh` - Generate deployment verification for any project - `deployment-verification-guide.md` - Complete implementation guide - `.deployment-check.sh` template with integration point testing - Git hook integration for mandatory verification before commit - **Skill Update Feedback Loop** - Meta-enforcement to ensure improvements flow back to skills - `install-skill-feedback-loop.sh` - One-command installation of automatic detection - `skill-update-feedback.md` - Full documentation of the feedback loop pattern - Automatic detection of enforcement improvements via git hooks - Semi-automatic commit system with human confirmation - Task queue (`.pending-skill-updates.txt`) for tracking updates - Archive system for processed improvements - **Fourth Failure Mode** - Documented "Skill Update Gap" as meta-enforcement challenge - Detection patterns for enforcement-related changes - Auto-categorization of which skill should be updated - Task generation with actionable steps ### Enhanced - **SKILL.md** - Now documents all 4 failure modes with enforcement strategies - **Enforcement Hierarchy** - Added meta-enforcement layer to the reliability stack - **Documentation** - Added comprehensive guides for deployment and feedback loop ### Fixed - Improved pattern matching in detection scripts - Better error handling in git hooks ## [1.0.0] - 2026-02-01 ### Added - Initial Release #### Core Scripts - `install.sh` - One-command installation for any project - `pre-create-check.sh` - List existing modules before creating new files - `post-create-validate.sh` - Detect duplicates, missing imports, bypass patterns - `check-secrets.sh` - Scan for hardcoded credentials #### Git Hooks - Pre-commit hook blocking bypass patterns - Pre-commit hook blocking hardcoded secrets - Customizable pattern matching #### Documentation - `SKILL.md` - Complete usage guide - `README.md` - Quick start and overview - `enforcement-research.md` - Why code > prompts for reliability - `agents-md-template.md` - Template for project-level enforcement rules - `SKILL_CN.md` - Chinese translation #### Assets - `pre-commit-hook` - Ready-to-install git hook - `registry-template.py` - Template for module registries ### Failure Modes Addressed (v1.0.0) 1. **Reimplementation** - Agent creates "quick version" instead of importing 2. **Hardcoded Secrets** - Credentials in code instead of env vars 3. **Deployment Gap** - Feature built but not wired to production ## [Unreleased] ### Planned for v1.2.0 - Phase 3: Fully automatic skill updates (AI-powered extraction) - Visual enforcement dashboard - Language support beyond bash (Python, Node.js) - Pre-built templates for common project types - Community pattern library ### Under Consideration - Integration with popular project scaffolding tools - Real-time enforcement monitoring - Team collaboration features - Cloud-based pattern sharing --- ## Migration Guides ### Upgrading from 1.0.0 to 1.1.0 No breaking changes. To add new features to existing installations: ```bash # Add deployment verification cd your-project/ bash /path/to/agent-guardrails/scripts/create-deployment-check.sh . # Add skill update feedback loop bash /path/to/agent-guardrails/scripts/install-skill-feedback-loop.sh . ``` Your existing hooks and scripts will continue to work unchanged. --- ## Credits Inspired by real production failures and the lesson that **mechanical enforcement > markdown rules**. Built with contributions from the AI agent development community. Special thanks to all early adopters who reported issues and suggested improvements. ```` ## File: CLAUDE_CODE_INSTALL.md size: 2288 sha: f89d426981edd12799ec488e545cc9ee53b26331 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/CLAUDE_CODE_INSTALL.md ````text # Installing Agent Guardrails for Claude Code ## Quick Install ```bash # Clone the skill git clone https://github.com/jzOcb/agent-guardrails # Install in your project cd your-project/ bash /path/to/agent-guardrails/scripts/install.sh . ``` ## What Gets Installed ✅ **Git Hooks** - Automatic enforcement on every commit ✅ **Validation Scripts** - Pre/post creation checks ✅ **Secret Detection** - Prevent credential leaks ✅ **Deployment Verification** - Ensure production integration ## Usage with Claude Code ### 1. Prevent Reimplementation Before creating new code: ```bash bash scripts/pre-create-check.sh . ``` Claude will see existing modules and import them instead of rewriting. ### 2. Validate Changes After editing code: ```bash bash scripts/post-create-validate.sh path/to/file.py ``` Catches duplicates, missing imports, bypass patterns. ### 3. Check Secrets Before committing: ```bash bash scripts/check-secrets.sh ``` Blocks hardcoded API keys, tokens, passwords. ### 4. Verify Deployment When feature is "done": ```bash bash .deployment-check.sh ``` Ensures code is actually wired to production (not just written). ## Automatic Mode After installation, git hooks run automatically: - Every commit → checks secrets, bypass patterns - Can't commit without passing checks ## Customization Edit `.git/hooks/pre-commit` to adjust patterns: ```bash # Add your own bypass patterns # Add your own secret patterns # Customize for your project ``` ## For Claude Code Agents When using Claude Code CLI with this skill: **Prompt enhancement:** ``` Before creating new code, run pre-create-check to see existing modules. After editing, run post-create-validate to ensure quality. Before marking "done", run .deployment-check to verify integration. ``` This ensures Claude Code agents respect your enforcement rules. ## Troubleshooting **Hook not running?** ```bash chmod +x .git/hooks/pre-commit ``` **Want to skip once?** ```bash git commit --no-verify -m "message" ``` **Need to update patterns?** Edit `scripts/post-create-validate.sh` and `.git/hooks/pre-commit` ## Learn More - [Full Documentation](./README.md) - [Deployment Guide](./references/deployment-verification-guide.md) - [Skill Update Loop](./references/skill-update-feedback.md) ```` ## File: GITHUB_TOPICS_GUIDE.md size: 1779 sha: 711bd52eb88170b5c7b4d561e120519a6b20c366 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/GITHUB_TOPICS_GUIDE.md ````text # How to Add GitHub Topics (Visual Guide) ## Step-by-Step ### 1. Go to Your Repo Visit: https://github.com/jzOcb/agent-guardrails ### 2. Click the Settings Gear Look for the "About" section on the right side → Click the ⚙️ gear icon ### 3. Add Topics In the "Topics" field, type each of these and press Enter: **Essential (Add these first):** ``` claude-code-skill clawdbot-skill ai-guardrails enforcement ``` **Recommended:** ``` git-hooks deployment-verification mechanical-enforcement ai-agents devtools code-quality ``` **Optional (for more discoverability):** ``` python bash automation ci-cd pre-commit-hooks ``` ### 4. Save Click "Save changes" ## What This Does ✅ **Claude Code users can find your skill:** - Search: "claude code skill enforcement" - Browse: https://github.com/topics/claude-code-skill - Recommended when searching for guardrails/quality tools ✅ **Skill appears in relevant categories:** - AI agents tools - Code quality - DevOps automation ✅ **Better GitHub SEO:** - Shows up in searches - Recommended to similar repos - Featured in topic pages ## Verification After adding topics, check: 1. Visit https://github.com/topics/claude-code-skill 2. Your repo should appear in the list 3. Click on it to verify it's showing properly ## Troubleshooting **Topics not showing?** - Make sure repo is public (not private) - Wait 1-2 minutes for GitHub to index - Refresh the page **Can't find the gear icon?** - Make sure you're logged in - Make sure you have write access to the repo - Try on desktop browser (mobile may not show) **Topics not saving?** - Check you have repo admin access - Try adding one at a time - Refresh and try again --- **Done? Your skill is now discoverable by both Claude Code and Clawdbot users! 🎉** ```` ## File: LICENSE size: 1062 sha: bd287e325952c81bdf56671381679a4e8d4bd03a upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/LICENSE ```text MIT License Copyright (c) 2026 jzOcb Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` ## File: PUBLISH_NOW.sh size: 1009 sha: 1a2fe0b4f6a1aa50a65a428050a76019bad08e73 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/PUBLISH_NOW.sh ```text #!/bin/bash # Quick publish script for agent-guardrails set -e SKILL_DIR="/home/clawdbot/clawd/skills/agent-guardrails" echo "📦 Publishing Agent Guardrails v1.1.0 to ClawdHub" echo "" # Check if logged in echo "1. Checking ClawdHub authentication..." if ! clawdhub whoami > /dev/null 2>&1; then echo " ⚠️ Not logged in" echo " Opening browser for login..." clawdhub login else echo " ✅ Already logged in" fi echo "" echo "2. Publishing skill..." cd "$SKILL_DIR" clawdhub publish . \ --slug agent-guardrails \ --name "Agent Guardrails" \ --version 1.1.0 \ --changelog "Meta-enforcement system: Deployment verification + skill update feedback loop. Prevents 4 common agent failure modes through mechanical enforcement." echo "" echo "✅ Published to ClawdHub!" echo "" echo "View at: https://clawdhub.com/skills/agent-guardrails" echo "" echo "Next steps:" echo " 1. Share on X/Twitter (see X_THREAD.md)" echo " 2. Post on LinkedIn" echo " 3. Share on Reddit" ``` ## File: PUBLISHING.md size: 7622 sha: 6ca86bc3698f450a2b3c13197abf1b0250c66687 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/PUBLISHING.md ````text # Publishing Agent Guardrails ## ClawdHub Publication ### Preparation Checklist - [x] README.md with clear description - [x] SKILL.md with usage instructions - [x] Working scripts in scripts/ - [x] Reference documentation in references/ - [x] Examples and templates in assets/ - [ ] VERSION file - [ ] CHANGELOG.md - [ ] skill.json metadata ### Metadata (skill.json) ```json { "name": "agent-guardrails", "version": "1.1.0", "description": "Mechanical enforcement tools to prevent AI agents from bypassing project standards. Prevents reimplementation, secret leaks, deployment gaps, and skill update gaps.", "author": "jzOcb", "license": "MIT", "repository": "https://github.com/jzOcb/agent-guardrails", "tags": [ "enforcement", "guardrails", "quality", "git-hooks", "automation", "meta-enforcement", "deployment", "security" ], "category": "development-tools", "requirements": { "bash": ">=4.0", "git": ">=2.0" }, "keywords": [ "AI agents", "code quality", "mechanical enforcement", "git hooks", "deployment verification", "secret detection", "skill updates" ] } ``` ### VERSION ``` 1.1.0 ``` ### CHANGELOG.md ```markdown # Changelog ## [1.1.0] - 2026-02-02 ### Added - Deployment verification system (`create-deployment-check.sh`) - Skill update feedback loop (`install-skill-feedback-loop.sh`) - Meta-enforcement: automatic detection of enforcement improvements - Semi-automatic commit system for skill updates - Comprehensive documentation for deployment gap prevention ### Enhanced - SKILL.md now documents all 4 failure modes - Added skill-update-feedback.md reference guide - Added deployment-verification-guide.md ## [1.0.0] - 2026-02-01 ### Initial Release - Pre-creation checks (prevent reimplementation) - Post-creation validation (detect duplicates, bypass patterns) - Secret detection (prevent hardcoded credentials) - Git hooks for enforcement - Project installation script - Full documentation and templates ``` --- ## Claude Skill Marketplace ### Required Files 1. **skill.json** - Metadata (see above) 2. **README.md** - Already have ✅ 3. **SKILL.md** - Already have ✅ 4. **LICENSE** - Need to add 5. **CHANGELOG.md** - See above 6. **VERSION** - See above ### Publication Steps ```bash # 1. Add missing files cd skills/agent-guardrails # 2. Create VERSION echo "1.1.0" > VERSION # 3. Create CHANGELOG.md # (see content above) # 4. Create skill.json # (see content above) # 5. Add LICENSE (MIT) # (see below) # 6. Test installation cd /tmp/test-project bash /path/to/agent-guardrails/scripts/install.sh . # 7. Publish to ClawdHub clawdhub publish agent-guardrails # or clawdhub publish --skill-dir ./skills/agent-guardrails ``` --- ## License (MIT) ``` MIT License Copyright (c) 2026 jzOcb Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ``` --- ## Marketing Copy ### Short Description (for listings) "Mechanical enforcement for AI agents. Prevents bypass patterns, secret leaks, deployment gaps, and ensures knowledge compounds across projects. 100% reliable through code hooks, not markdown rules." ### Long Description "Agent Guardrails provides mechanical enforcement tools that BLOCK common AI agent failures at the code level, not through unreliable markdown rules. **Problem:** AI agents forget important steps, bypass standards, and lose knowledge between projects. **Solution:** Git hooks and automated checks that make it impossible to commit without verification. **4 Failure Modes Prevented:** 1. Reimplementation (bypass patterns) 2. Hardcoded secrets 3. Deployment gaps (code works but not wired to production) 4. Skill update gaps (improvements don't flow back to shared skills) **Reliability:** 100% through code enforcement vs 40-50% through documentation. **One-command install:** Works with any project. Self-hosting feedback loop ensures continuous improvement." ### Use Cases - **For solo developers:** Never forget deployment steps again - **For teams:** Enforce standards mechanically, not through code reviews - **For AI agent developers:** Prevent common failure modes at the source - **For open source:** Ensure improvements compound across projects ### Screenshots/Demos 1. Pre-commit hook blocking a bypass pattern 2. Deployment check catching missing integration 3. Skill update task being auto-created 4. Before/after of enforcement pyramid --- ## Social Media Announcement ### Twitter Thread See X_THREAD.md for full 15-tweet thread. ### LinkedIn Post "After 3 days debugging why our AI agent kept 'forgetting' deployment steps, we realized the problem wasn't the agent — it was our enforcement strategy. We built Agent Guardrails: mechanical enforcement that makes it impossible to forget. Key insight: Markdown rules = 40% reliable. Git hooks = 100% reliable. Open sourced: [link] Claude skill: [link] [Full article: our journey from bug to meta-enforcement]" ### Reddit (r/ClaudeAI, r/LangChain, r/LocalLLaMA) Title: "Built mechanical enforcement for AI agents after 3-day deployment gap bug" Body: "TL;DR: If you work with AI agents, you've probably faced this: agent builds perfect code, marks task 'done,' but forgets to connect it to production. We built Agent Guardrails to mechanically prevent this. [Story of the problem] [The 5-layer enforcement hierarchy we discovered] [How we solved it with git hooks] [The meta twist: enforcing enforcement improvements] Open source: [GitHub] Claude skill: [link] Would love feedback from anyone else facing similar issues!" --- ## Launch Checklist ### Pre-Launch - [ ] All files in place (VERSION, CHANGELOG, LICENSE, skill.json) - [ ] Test installation in clean project - [ ] Test all 4 enforcement modes - [ ] Test skill update feedback loop - [ ] Documentation review - [ ] Fix any broken links ### Launch Day - [ ] Publish to ClawdHub - [ ] Publish to Claude Marketplace (if separate) - [ ] Post Twitter thread - [ ] Post LinkedIn article - [ ] Post Reddit threads (stagger by 1-2 hours) - [ ] Share in relevant Discord servers ### Post-Launch - [ ] Monitor feedback - [ ] Answer questions - [ ] Collect use cases - [ ] Plan v1.2 based on feedback --- ## Future Enhancements (v1.2+) Based on feedback, consider: - Phase 3: Fully automatic skill updates (AI-powered) - Visual dashboard for enforcement status - Integration with popular project templates - Language support beyond bash (Python, Node.js) - Pre-built templates for common project types - Community-contributed enforcement patterns --- **Ready to publish?** Let me know and I'll generate all the required files! ```` ## File: skill.json size: 1345 sha: 5f8de24079bde6877bac9259411ab243ea1fc076 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/skill.json ```text { "name": "agent-guardrails", "version": "1.1.0", "description": "Mechanical enforcement tools to prevent AI agents from bypassing project standards. Prevents reimplementation, secret leaks, deployment gaps, and skill update gaps.", "author": "jzOcb", "license": "MIT", "repository": "https://github.com/jzOcb/agent-guardrails", "homepage": "https://github.com/jzOcb/agent-guardrails#readme", "bugs": "https://github.com/jzOcb/agent-guardrails/issues", "tags": [ "enforcement", "guardrails", "quality", "git-hooks", "automation", "meta-enforcement", "deployment", "security", "ai-agents" ], "category": "development-tools", "requirements": { "bash": ">=4.0", "git": ">=2.0" }, "keywords": [ "AI agents", "code quality", "mechanical enforcement", "git hooks", "deployment verification", "secret detection", "skill updates", "agent reliability", "automated checks" ], "scripts": { "install": "bash scripts/install.sh", "install-deployment": "bash scripts/create-deployment-check.sh", "install-feedback": "bash scripts/install-skill-feedback-loop.sh" }, "installation": { "command": "bash scripts/install.sh /path/to/project", "postInstall": "Review .git/hooks/pre-commit and customize patterns as needed" } } ``` ## File: VERSION size: 6 sha: 9084fa2f716a7117829f3f32a5f4cef400e02903 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/VERSION ```text 1.1.0 ``` ## File: X_THREAD.md size: 4765 sha: 2b1e2c05355956be5c3d3719a76b4e8d22ec53d0 upstream: https://github.com/jzocb/agent-guardrails/blob/HEAD/X_THREAD.md ````text # X Thread: Building Agent Guardrails - A Meta-Enforcement Journey ## Thread Structure (15 tweets) --- **Tweet 1/15 - Hook** We spent 3 days solving a problem that keeps happening with AI agents: They build features perfectly... then forget to connect them to production. Here's how we built mechanical enforcement to stop it — and discovered something meta. 🧵 --- **Tweet 2/15 - The Problem** Feb 2, 2026. Our agent built: • News-verified trading signals • Dynamic position management • Improved hourly reports User: "Why are my reports still incomplete?" The agent forgot to update the CRON job. 😤 Code was perfect. Integration was missing. --- **Tweet 3/15 - Initial Response** First instinct: "Just remember to check next time!" But we've learned: Rules in markdown = wishful thinking. Agents don't "remember." They execute instructions. If it's not mechanically enforced, it WILL be forgotten. Time for a different approach. --- **Tweet 4/15 - The Research** We discovered enforcement has reliability layers: 🟢 Code hooks (100%) - Pre-commit blocks bad commits 🟡 Architecture (95%) - Import registries enforce reuse 🟠 Self-verification (80%) - Agent checks own work 🔴 Prompt rules (60-70%) - AGENTS.md guidelines ⚫ Markdown (40-50%) - Degrades with context Rule: Move UP the stack. --- **Tweet 5/15 - Failure Mode #1: Reimplementation** Agent writes "quick version" instead of importing validated code. ❌ Markdown rule: "Don't reimplement" ✅ Code hook: Blocks commits containing "quick version" Result: 100% enforcement. Can't commit without review. --- **Tweet 6/15 - Failure Mode #2: Secrets** Agent hardcodes API keys instead of using env vars. ❌ Markdown rule: "Use environment variables" ✅ Code hook: Scans for patterns, blocks on detection One dev leaked a token once. Never again. --- **Tweet 7/15 - Failure Mode #3: Deployment Gap** The HARD one. Agent builds feature, marks "done," but: • CRON still calls old version • User never receives benefit • Only surfaces when user complains This is what broke us. --- **Tweet 8/15 - The Solution: .deployment-check.sh** Before ANY commit: ```bash ✅ Run actual production flow ✅ Verify output exists ✅ Check output format ✅ Test ALL integration points ❌ Block if any test fails ``` Git hook makes it impossible to "forget." --- **Tweet 9/15 - But Wait... There's More** We built deployment verification. Committed it. Then realized: "We forgot to update the agent-guardrails SKILL itself." 😅 We just discovered a META failure mode. --- **Tweet 10/15 - Failure Mode #4: Skill Update Gap** Project A builds enforcement improvement. → Works great in Project A → Projects B, C, D never know about it → Knowledge stays siloed We needed enforcement FOR enforcement improvements. Meta-enforcement. 🤯 --- **Tweet 11/15 - The Feedback Loop** Built automatic detection: ``` Commit improvement → Git hook detects pattern → Creates task → Human reviews → Updates skill → Semi-auto commit → Other projects benefit ``` Can't forget anymore. Mechanical. --- **Tweet 12/15 - Bootstrapping Paradox** When we built the auto-detection system: • It didn't exist yet • So it couldn't detect itself being created • We had to manually apply it the FIRST time After that? Self-hosting. The system detects its own improvements. --- **Tweet 13/15 - The Skill** All of this is now packaged as "Agent Guardrails": 📦 Scripts for all 4 failure modes 📖 Full documentation 🔧 One-command installation 🔄 Self-updating feedback loop Open source: github.com/jzOcb/agent-guardrails --- **Tweet 14/15 - Key Lessons** 1. Markdown rules = suggestions (40-50% reliable) 2. Code hooks = laws (100% reliable) 3. If agent keeps forgetting → don't remind, BLOCK 4. Meta-enforcement: enforce that improvements are preserved 5. Bootstrapping always requires manual first step --- **Tweet 15/15 - Try It** If you work with AI agents and face similar issues: ```bash git clone https://github.com/jzOcb/agent-guardrails cd your-project bash agent-guardrails/scripts/install.sh . ``` Or on Claude: [skill link TBD] Share your enforcement challenges below! 👇 --- ## Alternative: LinkedIn Long-form [Same story but as a single article, 1500-2000 words, with code examples and diagrams] ## Alternative: Blog Post [Full technical deep-dive with implementation details, 3000+ words] --- ## Media Assets Suggested diagrams: 1. Enforcement reliability pyramid (5 layers) 2. Before/After workflow comparison 3. Meta-enforcement feedback loop 4. Bootstrapping paradox visualization Let me know if you want me to describe these for a designer! ````