Shadows Deploy Guardian

Pre-deployment verification checklist — tests, types, build, secrets scan, environment validation. Use before pushing to production or staging.

Security Scan

The skill's instructions match its stated purpose (a pre-deployment checklist) but they execute project tests/builds and run grep/git commands that can execute repository code or reveal secrets, so run it only in trusted or sandboxed environments.

Purpose & Capability

Name and description describe a pre-deploy checklist (tests, lint, build, secrets scan, env validation) and the SKILL.md implements those gates directly. Required binaries (git + one of npm/python/cargo) are consistent with detecting and exercising common project toolchains.

Instruction Scope

The instructions explicitly run tests, builds, linters and git history scans; these are expected for a pre-deploy tool but also mean the agent will execute repository code and parse commit history. The SKILL.md itself warns about sandboxing. Also Gate 6 references $DEPLOY_URL (optional) and the secrets-scan grep will print matched lines to stdout — outputs may contain secret-like strings and could be logged/shared.

Install Mechanism

No install spec and no code files — instruction-only skill. This reduces install-time risk because nothing is downloaded or written by the skill itself.

Credentials

The skill declares no required environment variables (reasonable), but the instructions reference an optional $DEPLOY_URL and .env/.env.example handling. This is a minor inconsistency (uses optional env vars without declaring them), and the instructions may surface secret-like values in output. The skill does not request any credentials or secrets itself.

Persistence & Privilege

always is false, disable-model-invocation is not set (normal), and there are no config paths or claims of persistent system modification. The skill does not request permanent presence or elevated privileges.

Assessment

This skill appears to be what it says — a pre-deployment checklist — but it will run your repo's tests/builds/linters and inspect git history. Those operations can execute arbitrary code from the repository and may print secret-like strings to stdout. Before installing or invoking: 1) run it on a cloned or sandboxed copy (not directly in a production environment); 2) ensure CI/runner environment isolates network and credentials; 3) be aware the secrets-scan uses grep and can echo matched text to logs — use a dedicated secret scanner (gitleaks/detect-secrets) for production-sensitive work; 4) note minor docs issues (it references DEPLOY_URL and Docker but Docker isn't listed in required bins, and 'docker build --dry-run' is not a standard docker flag) — review and adapt the commands to your environment before running. If you want higher assurance, request a version with explicit opt-in checks and no direct stdout of potential secrets.

Deploy Guardian — Pre-Deployment Verification

Version: 1.1.0 | Author: Shadows Company | License: MIT

---

WHEN TO TRIGGER

• Before deploying to production or staging
• User says "deploy check", "ready to deploy?", "pre-deploy", "deploy guardian"
• Before creating a release tag
• Before merging a major PR

WHEN NOT TO TRIGGER

• Local development iterations
• Draft PRs or WIP branches
• Exploratory prototyping with no deployment intent

---

PREREQUISITES

This skill requires git on PATH. Gates 2-4 auto-detect and run only the toolchain present in the project:

Toolchain	Required for	Detection
npm/npx	Node.js projects	package.json exists
python/python3	Python projects	setup.py, pyproject.toml, or requirements.txt exists
cargo	Rust projects	Cargo.toml exists
docker	Containerized builds	Dockerfile exists

The agent MUST check which toolchain is available before running commands. Skip any gate sub-step whose toolchain is absent — do NOT fail the gate for missing optional toolchains.

---

PROTOCOL — 6 GATES

Each gate must PASS before proceeding. One FAIL = deployment blocked.

Gate 1 — GIT STATUS

git status
git log --oneline -5
git remote update --prune 2>/dev/null && git status -uno

Verify:

• Working tree is clean (no uncommitted changes)
• On the correct branch (main/release/deploy)
• Branch is up to date with remote (git rev-parse HEAD == git rev-parse @{u})
• No merge conflicts pending

Gate 2 — TESTS

Detect the project type and run ONLY the matching test runner:

# Auto-detect: run the FIRST matching runner only
if [ -f package.json ]; then
  npm test 2>&1
elif [ -f pyproject.toml ] || [ -f setup.py ] || [ -f requirements.txt ]; then
  python -m pytest -v 2>&1 || python3 -m pytest -v 2>&1
elif [ -f Cargo.toml ]; then
  cargo test 2>&1
else
  echo "SKIP: No recognized test runner found"
fi

Verify:

• All tests pass (zero failures)
• No skipped critical tests
• Exit code is 0

Note: This executes project test scripts, which run code from the repository. Only run in trusted repositories or sandboxed environments.

Gate 3 — TYPE CHECK & LINT

Auto-detect and run ONLY the matching toolchain:

# TypeScript (if tsconfig.json exists)
[ -f tsconfig.json ] && npx tsc --noEmit 2>&1

# Python (if .py files exist)
[ -f pyproject.toml ] && python -m ruff check . 2>&1

# ESLint (if .eslintrc* exists)
ls .eslintrc* eslint.config.* 2>/dev/null && npx eslint . 2>&1

Verify:

• Zero type errors
• Zero lint errors (warnings acceptable)
• SKIP if no type checker / linter is configured (not a failure)

Gate 4 — BUILD

Auto-detect and run ONLY the matching build system:

if [ -f package.json ] && grep -q '"build"' package.json; then
  npm run build 2>&1
elif [ -f Dockerfile ]; then
  docker build --dry-run . 2>&1
elif [ -f Cargo.toml ]; then
  cargo build --release 2>&1
else
  echo "SKIP: No build step detected"
fi

Verify:

• Build completes with exit code 0
• Output artifacts generated in expected location
• SKIP if no build system detected (not a failure)

Note: Build commands execute project scripts. Same sandboxing considerations as Gate 2 apply.

Gate 5 — SECRETS SCAN

# Check for leaked secrets in recent commits (last 5)
git diff HEAD~5..HEAD -- . ':!*.lock' ':!*.sum' | grep -inE "(api[_-]?key|secret|token|password|private[_-]?key)\s*[:=]\s*['\"][^'\"]{8,}" || echo "PASS: No secrets pattern detected"

# Check .env files not committed to git
git ls-files | grep -E "\.env$|\.env\.\w+" | head -10

# Check .gitignore has secret patterns
if [ -f .gitignore ]; then
  COVERAGE=$(grep -cE "\.env|secret|credential|\.pem|\.key" .gitignore)
  echo "Gitignore secret coverage: $COVERAGE patterns"
fi

Verify:

• No secrets pattern in recent commits
• Zero .env files tracked by git
• .gitignore covers at least 3 secret patterns
• No .pem, .key, .p12 files tracked

Limitations: This grep-based scan catches common patterns but is not a substitute for dedicated secret scanners (gitleaks, trufflehog, detect-secrets). For production environments, consider running a dedicated scanner as an additional step.

Warning: Command output may display matched secret-like patterns in the terminal. Run this gate in a secure terminal session where output is not logged to shared systems.

Gate 6 — ENVIRONMENT VALIDATION

Run concrete automated checks for the target environment:

# Check required env vars are documented
if [ -f .env.example ]; then
  echo "PASS: .env.example exists ($(wc -l < .env.example) vars documented)"
else
  echo "WARN: No .env.example — required variables not documented"
fi

# Check for pending database migrations (common frameworks)
[ -d migrations ] && ls -1t migrations/ | head -3
[ -d alembic/versions ] && ls -1t alembic/versions/ | head -3

# Check SSL cert validity (if curl available)
if command -v curl &>/dev/null && [ -n "$DEPLOY_URL" ]; then
  curl -sI --max-time 5 "$DEPLOY_URL" | head -5
fi

# Check Docker health (if applicable)
[ -f docker-compose.yml ] && docker compose config --quiet 2>&1 && echo "PASS: docker-compose config valid"

Verify:

• .env.example or equivalent documentation exists
• No unapplied migrations in queue
• Target URL responds (if $DEPLOY_URL is set)
• Docker config valid (if applicable)
• SKIP individual checks when not applicable (not a failure)

---

SECURITY CONSIDERATIONS

1. Code execution: Gates 2-4 execute project scripts (npm test, npm run build, cargo test). These commands run arbitrary code from the repository. Only run this skill on repositories you trust, or execute within a sandboxed environment (Docker container, CI/CD pipeline, OpenClaw sandbox mode).

2. Secret exposure: Gate 5 scans diffs for secret patterns. Matched patterns are displayed in terminal output. Ensure your terminal session is not logged to shared monitoring systems.

3. Network access: Gate 6 optionally makes outbound HTTP requests (via curl) only if $DEPLOY_URL is explicitly set. No other network access is required.

4. No persistence: This skill does not modify any configuration files, install packages, store credentials, or make changes outside the terminal session. It is read-only except for the build artifacts produced by Gate 4.

5. Sandboxing recommendation: For maximum safety, run deploy-guardian inside a CI/CD pipeline or a sandboxed agent environment rather than directly on a developer workstation.

---

OUTPUT FORMAT

# Deploy Guardian Report
**Date**: [YYYY-MM-DD HH:MM]
**Branch**: [branch name]
**Commit**: [short SHA]
**Target**: [production/staging]
**Toolchain**: [detected: node/python/rust/docker]

## Gate Results

| # | Gate | Status | Details |
|---|------|--------|---------|
| 1 | Git Status | PASS/FAIL | [clean, correct branch, up to date] |
| 2 | Tests | PASS/FAIL/SKIP | [X passed, Y failed, or skipped reason] |
| 3 | Type Check & Lint | PASS/FAIL/SKIP | [errors count or skipped reason] |
| 4 | Build | PASS/FAIL/SKIP | [success or error summary] |
| 5 | Secrets Scan | PASS/FAIL | [patterns found or clean] |
| 6 | Environment | PASS/WARN/SKIP | [checks run and results] |

## Verdict: [CLEAR TO DEPLOY / BLOCKED / CLEAR WITH WARNINGS]

## Blockers (if any)
1. [What needs to be fixed — file:line reference]

## Warnings (if any)
1. [Non-blocking issues to be aware of]

## Recommended Deployment Command
[The actual deploy command to run]

---

RULES

1. All gates must pass — no exceptions, no overrides
2. Secrets gate is non-negotiable — one leaked secret = full stop
3. Auto-detect toolchain — never run commands for absent toolchains
4. SKIP is not FAIL — absent toolchains produce SKIP, not FAIL
5. Test failures block deployment — even flaky tests must be investigated
6. Document blockers — always explain WHY with file:line references
7. Never auto-deploy — always wait for explicit user confirmation
8. Trusted repos only — warn user if running on an unfamiliar repository

---

Published by Shadows Company — "We work in the shadows to serve the Light."