agentic-validators

name	agentic-validators
description	Design and install validation hooks for coding agents (e.g., Claude Code) to make AI changes safer and more deterministic. Use when you want post-tool-use or stop hooks, automated tests/linters/formatters, parallel subagents with per-file validation, or a repeatable “agent pipeline” with audit logs.
license	MIT
metadata	{"author":"Vishal Sachdev + Pip","version":"0.1.0","tags":"agents hooks validation testing linting formatting ci"}
compatibility	Works in repos on macOS/Linux with bash. Assumes a CLI coding agent that supports hooks (Claude Code-style) and common tooling (git, ripgrep, node/python toolchains).

Agentic Validators

Goal

Turn “agent wrote code” into “agent wrote code and the change is validated automatically.”

This skill helps you:

• choose the right validation strategy (per-file vs repo-wide)
• implement post-tool-use and stop hooks
• create narrow validators (fast, deterministic checks)
• structure work so multiple agents can run in parallel without losing correctness

Mental model

• Agents are non-deterministic; validators are deterministic.
• Context is fragile; validation + logs are durable.
• Prefer small, fast checks close to the change (per-file) + a final global gate (repo-wide).

When to use which hook

Post-tool-use hook (best default)

Use when:

• you want immediate feedback after edits
• you can validate the specific file(s) that were touched
• you want high signal without running the full test suite

Typical checks:

• formatting (prettier/black)
• linting (eslint/ruff)
• typecheck for that file/module (tsc --noEmit with project config)

Stop hook (end-of-run gate)

Use when:

• you need repo-wide invariants
• you want one last “exit criteria” check

Typical checks:

• unit tests
• build
• integration tests

Step-by-step: add validators to a repo

1. Identify file types and fast checks

   • JS/TS: prettier + eslint + typecheck
   • Python: ruff + pytest (optional)
   • Go: gofmt + go test (optional)

2. Implement per-file validator(s)

   • A validator should be:
     • fast (<5–30s)
     • deterministic
     • clear output
     • safe to run repeatedly

3. Wire into hooks

   • Implement post-tool-use hook calling validator with the file path.

4. Add logs

   • Write to a predictable location (e.g., .agent-logs/validators.log)

5. Add a stop-hook “final gate”

   • Run the broader checks once.

Example validator patterns

Pattern A: “format + lint” for a touched file

• Format file
• Lint file
• If any change was made by formatter, fail and ask agent to re-run with formatter changes committed

Pattern B: “contract test”

• For touched module, run a focused unit test subset

Pattern C: “readme/docs invariant”

• If docs changed, run markdown lint + link checker

Parallelism pattern

If you have many similar files (CSV, configs, docs):

• spawn one subagent per file
• each subagent runs its own post-tool-use validator
• aggregator agent only accepts results where validators passed

Common failure modes & fixes

• Validator too slow → split into fast per-file checks + slower stop hook.
• Validator flaky → remove network calls, pin versions, add retries only where safe.
• Agent ignores tool docs → write a short “constitution” section and point to reference files.

References

• See Hook recipes
• See Validator design checklist