Skill: olmmlo-cmd/agent-guardrails (version 1.0.0)

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

path: CHANGELOG.md
content: # 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.


path: CLAUDE_CODE_INSTALL.md
content: # 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)


path: GITHUB_TOPICS_GUIDE.md
content: # 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! 🎉**


path: PUBLISHING.md
content: # 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!


path: PUBLISH_NOW.sh
content: #!/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"


path: README.md
content: # 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)

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

## Related

- [config-guard](https://github.com/jzOcb/config-guard) — Prevent AI agents from crashing OpenClaw by validating config changes (auto-backup, schema validation, auto-rollback)
- [upgrade-guard](https://github.com/jzOcb/upgrade-guard) — Safe OpenClaw upgrades with snapshot, verification, auto-rollback, and OS-level watchdog

## License

MIT — Use it, share it, make your agents behave.


path: X_THREAD.md
content: # 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!


path: _meta.json
content: ownerId: jzOcb-agent-guardrails
slug: agent-guardrails
version: 1.1.0

path: assets/init-registry-template.py
content: """
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


path: assets/registry-template.py
content: """
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


path: references/SKILL_CN.md
content: # 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


path: references/agents-md-template.md
content: # 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?


path: references/deployment-verification-guide.md
content: # 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.


path: references/enforcement-research.md
content: # 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


path: references/skill-update-feedback.md
content: # 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.


path: scripts/check-secrets.sh
content: #!/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


path: scripts/create-deployment-check.sh
content: #!/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"


path: scripts/install-skill-feedback-loop.sh
content: #!/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."


path: scripts/install.sh
content: #!/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 "╚══════════════════════════════════════════════════╝"


path: scripts/post-create-validate.sh
content: #!/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


path: scripts/pre-create-check.sh
content: #!/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 "╚══════════════════════════════════════════════════╝"


path: skill.json
content: {
  "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"
  }
}


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)