Agent Guardrails

26 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

• SKILL.md6.3 KB8d8185fb6e6cupstream ↗

  ---
  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.
  

• README.md8.0 KBfa8e3837edb1upstream ↗

  # 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)
  

• scripts/check-secrets.sh6.8 KBf950777eb2c6upstream ↗

  #!/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
  

• scripts/create-deployment-check.sh5.8 KBf3de91aefa0aupstream ↗

  #!/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
  
  <!-- Document your specific entry points here -->
  
  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"
  

• scripts/install-skill-feedback-loop.sh6.1 KB139e3301a25cupstream ↗

  #!/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."
  

• scripts/install.sh3.4 KBa1d848b35a86upstream ↗

  #!/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 <file>   ║"
  echo "║  Scan for secrets:                               ║"
  echo "║    bash scripts/check-secrets.sh .               ║"
  echo "╚══════════════════════════════════════════════════╝"
  

• scripts/post-create-validate.sh4.7 KB444e3ebda1e6upstream ↗

  #!/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 <file_path>
  
  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 <file_path>"
      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
  

• scripts/pre-create-check.sh3.6 KB9e61e818e941upstream ↗

  #!/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 "╚══════════════════════════════════════════════════╝"
  

• references/agents-md-template.md1.6 KB4f767a85b750upstream ↗

  # 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 <file_path>
  ```
  
  ### 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?
  

• references/deployment-verification-guide.md6.9 KBd5fbb270b2d3upstream ↗

  # 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.
  

• references/enforcement-research.md3.7 KB21c2628335b5upstream ↗

  # 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
  

• references/skill-update-feedback.md5.0 KB61ee4f09bfdaupstream ↗

  # 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.
  

• references/SKILL_CN.md5.1 KBe11bb0b0bf7cupstream ↗

  # 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
  

• assets/init-registry-template.py1.2 KB0879e7f86cb8upstream ↗

  """
  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
  

• assets/pre-commit-hook2.7 KB118ce2d3a478upstream ↗

  #!/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
  

• assets/registry-template.py1.5 KBe2e5cf9c9b59upstream ↗

  """
  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
  

• .gitignore20 B7aaee7cbdce3upstream ↗

  LISTING-STRATEGY.md
  

• CHANGELOG.md3.9 KB1633353dceccupstream ↗

  # 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.
  

• CLAUDE_CODE_INSTALL.md2.2 KBf89d426981edupstream ↗

  # 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)
  

• GITHUB_TOPICS_GUIDE.md1.7 KB711bd52eb881upstream ↗

  # 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! 🎉**
  

• LICENSE1.0 KBbd287e325952upstream ↗

  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.
  

• PUBLISH_NOW.sh1009 B1a2fe0b4f6a1upstream ↗

  #!/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"
  

• PUBLISHING.md7.4 KB6ca86bc3698fupstream ↗

  # 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!
  

• skill.json1.3 KB5f8de24079bdupstream ↗

  {
    "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"
    }
  }
  

• VERSION6 B9084fa2f716aupstream ↗

  1.1.0
  

• X_THREAD.md4.7 KB2b1e2c053559upstream ↗

  # 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!
  

Plain-text copy, no login: /skill-bundles/agent-guardrails.md