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)

1. Implement per-file validator(s)

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

1. Wire into hooks

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

1. Add logs

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

1. 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](references/HOOK_RECIPES.md)
• See [Validator design checklist](references/VALIDATOR_CHECKLIST.md)