| name | enhance-agent-guardrails |
| description | Install guardrails-as-code into a repo so AI/vibe-coding can't keep reintroducing the same classes of problems (leaked secrets, injection, off-system styles, untested code, hallucinated or vulnerable dependencies, destructive shell/DB ops). Audits what protection already exists, then sets up a tailored stack: agent policy files (.cursor/rules + AGENTS.md), a pre-commit hook (secret scan + SAST + lint/typecheck), a CI gate that treats agent output as untrusted, and lint-as-policy rules. Use when "set up guardrails", "stop vibe-coding regressions", "add pre-commit security checks", "protect the repo from AI mistakes", "add CI security gates", "governance for AI code", or "enhance-agent-guardrails". Configures tooling; CI/secret-scanner changes are flagged for human review before they block merges. |
| license | MIT |
enhance-agent-guardrails โ Guardrails-as-Code Against AI Regressions
AI agents ship the visible 80% fast and skip the 20% that keeps a repo safe. Studies in
2026 put ~45% of AI-generated code shipping OWASP Top-10 issues, ~2.74ร more security
findings per PR, and repeated production disasters from unguarded destructive actions.
Telling the agent to "be secure" doesn't work โ deterministic gates do. This skill
installs those gates so the next fast session can't quietly reintroduce old classes of bugs.
Treat all agent output as untrusted until a machine check says otherwise. The goal is
guardrails that block at the moment of creation (pre-commit) and again before merge
(CI), plus policy files that steer the agent up front. Additive and reversible โ never
weaken an existing check to make the setup "pass".
Phase 0 โ Detect stack and existing protection
cat package.json 2>/dev/null | grep -iE "husky|lint-staged|semgrep|gitleaks|eslint|prettier|typescript"
ls -la .husky/ .github/workflows/ 2>/dev/null
ls .cursor/rules/ AGENTS.md CLAUDE.md .pre-commit-config.yaml 2>/dev/null
rg -n "gitleaks|trufflehog|semgrep|npm audit|osv-scanner|socket" .github/ .husky/ 2>/dev/null
Record: package manager, CI provider (GitHub Actions / other), existing hooks, existing
rules/policy files, and which checks already run. Don't duplicate what's present โ
extend it.
Phase 1 โ Research current practice
Follow /research: current-year guidance on AI-code guardrails (VibeSec / OWASP), and the
current invocation for the scanners you'll wire (gitleaks, semgrep, osv-scanner/npm audit,
socket). Pin tool versions rather than floating latest.
Phase 2 โ Gap map (which failure classes are unguarded)
Map the documented AI failure classes to the repo's current coverage and pick what to add:
| Failure class | Guard to add (if missing) |
|---|
| Hardcoded secrets / credential sprawl | Secret scan (gitleaks / trufflehog) in pre-commit and CI |
| Injection / XSS / SSRF / OWASP | SAST (semgrep with a ruleset for the stack) in CI |
| Vulnerable / hallucinated dependencies | npm audit / osv-scanner / socket in CI; lockfile required |
| Off-system / drifting styles | Lint-as-policy (no raw hex, no arbitrary values, single icon lib) |
| Untested "plausible" code | CI requires typecheck + test to pass; coverage floor if one exists |
| Destructive shell/DB ops | Agent policy: human-in-the-loop for rm -rf, migrations, prod scripts |
| Context/spec drift & false-done | Point agents at verification-before-completion + completion-judge |
Phase 3 โ Install the guardrails
Install only the missing pieces. Keep each additive and clearly named.
3a. Agent policy files (steer up front)
.cursor/rules/*.mdc and/or AGENTS.md: encode the non-negotiables as rule-as-code โ
parameterized queries only, validate/sanitize all external input, no hardcoded secrets,
auth middleware on protected routes, no destructive ops without explicit human
approval, write tests for new features. Ground it in the OWASP Top 10.
3b. Pre-commit hook (block at creation)
- Wire the repo's hook manager (
husky + lint-staged for Node, or
.pre-commit-config.yaml): run secret scan on staged files, lint + typecheck on changed
files, and fail the commit on any finding. Keep it fast (staged-only).
3c. CI gate (block before merge โ the authoritative gate)
- Add/extend a CI job that treats agent output as untrusted: secret scan (full history or
diff), SAST, dependency audit, typecheck, lint, test. Fail the PR on high-severity
findings. This is the gate that matters even if a local hook is skipped.
3d. Lint-as-policy
- Add rules that block off-system patterns (
no-restricted-syntax, raw color/arbitrary-value
rules, no-console where appropriate, @typescript-eslint/no-explicit-any) with a
documented, reviewed escape hatch โ so rules get exceptions, not blanket-disabled.
Phase 4 โ Verify the guards actually bite
A guardrail you didn't test is a guardrail that doesn't work.
- Plant-and-check (dry run): temporarily introduce a fake secret / off-system value in a
scratch file and confirm the pre-commit hook and/or the scanner blocks it; then remove
it. Never commit the planted value.
- Run the lint-as-policy rules against the current tree and report (don't mass-
--fix
silently โ surface what would change).
- Confirm the CI workflow is valid (
act/yamllint if available, or a draft PR).
Phase 5 โ Report + handoff
## Agent Guardrails โ report
**Already present:** [hooks/CI/rules found]
**Installed:** agent policy [files] ยท pre-commit [checks] ยท CI gate [checks] ยท lint-as-policy [rules]
**Verified:** planted secret blocked โ ยท lint rules run โ ยท CI workflow valid โ
**Needs human review before enforcing:** [CI changes that will block merges / branch protection]
**Not covered here (route to):** deep secrets audit โ plan-secrets-audit ยท OWASP depth โ plan-security-audit
STOP for the human before turning on anything that blocks merges in a shared repo
(branch protection, required CI checks) or that rewrites history. Rotating real leaked
secrets is out of scope โ route to plan-secrets-audit.
Related
audit-security / plan-security-audit โ the vulnerability depth the SAST gate can't fully coverplan-secrets-audit โ find + triage existing leaked secrets (and rotation plan)plan-dependency-provenance โ hallucinated/slopsquatted dependency auditplan-data-integrity โ destructive-operation and data-loss guardrailsverification-before-completion (rule) + completion-judge โ the false-done guard agents should obeyhousekeep-design โ pairs the visual lint-as-policy with a full design consolidation
