| name | add-check |
| description | Scaffold a new IAM policy validation check with proper structure, tests, and registration. Use when the user wants to add a new check, create a new validation rule, scaffold a check, or implement a new policy check. Triggers on "/add-check", "add a new check", "create a new validation check", or "scaffold a check". |
Add Check
Scaffold a new IAM policy validation check end-to-end.
Workflow
Given the check name argument: $ARGUMENTS
1. Parse Check Name
- Convert to snake_case for
check_id (e.g., my_check)
- Convert to PascalCase for class name (e.g.,
MyCheck)
- If no argument, ask for: check name, description, severity
2. Ask Clarifying Questions
- What does this check validate?
- What severity level? (low, medium, high, critical, error, warning)
- What check type?
- Statement-level (
execute) — runs per statement. For individual actions, resources, conditions.
- Policy-level (
execute_policy) — runs per policy. For cross-statement validation, aggregate analysis, policy-wide constraints.
- Combined (both) — for checks needing both per-statement AND policy-wide analysis.
- What
issue_type category? (e.g., overly_permissive, invalid_action, policy_structure)
3. Create Check File
Create iam_validator/checks/{check_name}.py using the appropriate template from references/templates.md.
4. Update Imports
Add to iam_validator/checks/__init__.py:
from iam_validator.checks.{check_name} import {CheckName}Check
5. Register the Check
Add to iam_validator/core/check_registry.py in create_default_registry():
registry.register(checks.{CheckName}Check())
6. Create Test File
Create tests/checks/test_{check_name}_check.py using the appropriate test template from references/templates.md.
7. Verify
uv run ruff check iam_validator/checks/{check_name}.py
uv run ruff format iam_validator/checks/{check_name}.py
uv run pytest tests/checks/test_{check_name}_check.py -v
8. Update Defaults
- Update
iam_validator/core/config/defaults.py with new check's default config
- Update
examples/configs/full-reference-config.yaml
9. Update Documentation
- CHANGELOG.md: Add entry under
### Added for the in-progress version
iam_validator/checks/CLAUDE.md: Add a row to the "Built-in checks" table- docs/user-guide/checks/: Add a page if user-facing
Reference Checks by Type
Statement-Level: wildcard_action.py, wildcard_resource.py, action_validation.py, condition_key_validation.py
Policy-Level: sid_uniqueness.py, policy_size.py, policy_structure.py, policy_type_validation.py
Combined: action_condition_enforcement.py, sensitive_action.py
Examples
/add-check require_vpc_restriction — statement-level/add-check duplicate_permission_detection — policy-level/add-check tag_enforcement — will ask for type
