Skip to content
Agentic InfraOps

Validation and Linting Reference

Central reference for all validation scripts, linting commands, git hooks, and CI workflows.

Validation Architecture

Section titled “Validation Architecture”

Validation runs at three stages, catching issues progressively earlier:

flowchart LR
    A["Pre-Commit<br/>(lefthook)"] --> B["Pre-Push<br/>(lefthook)"]
    B --> C["CI<br/>(GitHub Actions)"]
    style A fill:#e8f5e9,stroke:#4caf50,color:#000
    style B fill:#fff3e0,stroke:#ff9800,color:#000
    style C fill:#ffebee,stroke:#f44336,color:#000
  1. Pre-commit — validates staged files only (fast, file-type scoped)
  2. Pre-push — validates all changed files vs main (domain-scoped, parallel)
  3. CI — validates the full repository on every PR and push to main

A post-commit layer also runs lightweight checks after each commit.

Lefthook Hooks

Section titled “Lefthook Hooks”

All hooks are defined in lefthook.yml at the repository root.

Pre-Commit Hooks

Section titled “Pre-Commit Hooks”
HookTrigger (glob)Purpose
markdown-lint*.mdmarkdownlint on staged markdown files
link-checkdocs/**/*.mdVerify URLs in staged docs files
h2-syncSKILL.md, azure-artifacts filesCheck H2 heading sync across sources
artifact-validationagent-output/**/*.mdValidate artifact H2 structure against templates
agent-frontmatter**/*.agent.mdValidate agent YAML frontmatter syntax
model-alignment**/*.agent.md, **/*.prompt.mdCheck model-prompt alignment
agent-checks**/*.agent.mdAgent body size and language density
instruction-checks**/*.instructions.mdInstruction frontmatter validation
instruction-refsAgents, skills, instructionsCross-reference validation
python-lintmcp/**/*.pyRuff linter on Python files
terraform-fmt*.tfTerraform formatting check
terraform-validate*.tfTerraform validation per project

Commit-Msg Hook

Section titled “Commit-Msg Hook”
HookPurpose
commitlintEnforce Conventional Commits format

Pre-Push Hooks

Section titled “Pre-Push Hooks”
HookPurpose
branch-namingValidate branch name uses an approved prefix
branch-scopeValidate domain branches only modify in-scope files
diff-based-checkRun domain-scoped validators for changed file types

Post-Commit Hooks

Section titled “Post-Commit Hooks”
HookPurpose
version-syncCheck version consistency across VERSION.md, package.json, mkdocs.yml
deprecated-refsDetect deprecated references in changed markdown
json-syntaxValidate JSON syntax of changed .json files

Validation Scripts

Section titled “Validation Scripts”

All scripts are in the scripts/ directory. Run via npm run <command>.

Architecture and Registry Validators

Section titled “Architecture and Registry Validators”
npm CommandScriptPurpose
lint:agent-frontmattervalidate-agent-frontmatter.mjsAgent definition frontmatter compliance
lint:agent-checkslint-agent-checks.mjsAgent body size (≤350 lines) and language density
lint:model-alignmentlint-model-alignment.mjsModel-specific prompt pattern compliance
lint:skills-formatvalidate-skills-format.mjsSkill file format and frontmatter
validate:skill-checksvalidate-skill-checks.mjsSkill size (≤500 lines) and references
validate:instruction-checksvalidate-instruction-checks.mjsInstruction frontmatter and applyTo patterns
validate:agent-registryvalidate-agent-registry.mjsAgent registry consistency
validate:skill-affinityvalidate-skill-affinity.mjsSkill-to-agent affinity mappings
validate:workflow-graphvalidate-workflow-graph.mjsDAG integrity (no orphans, no cycles)

Artifact and Template Validators

Section titled “Artifact and Template Validators”
npm CommandScriptPurpose
lint:artifact-templatesvalidate-artifact-templates.mjsH2 heading strictness for agent outputs
lint:h2-syncvalidate-h2-sync.mjsH2 heading consistency across three sources
fix:artifact-h2fix-artifact-h2.mjsAuto-fix artifact H2 headings
e2e:validatevalidate-e2e-step.mjsE2E pipeline structural validation
e2e:benchmarkbenchmark-e2e.mjs8-dimension benchmark scoring

Governance and Compliance Validators

Section titled “Governance and Compliance Validators”
npm CommandScriptPurpose
lint:governance-refsvalidate-governance-refs.mjsGovernance guardrails integrity
validate:no-hardcoded-countsvalidate-no-hardcoded-counts.mjsPrevent hardcoded entity counts
validate:stale-refsvalidate-no-stale-skill-references.mjsDetect stale skill references
lint:deprecated-refsvalidate-no-deprecated-refs.mjsBlock deprecated API/pattern references
validate:iac-security-baselinevalidate-iac-security-baseline.mjsIaC security baseline (TLS, HTTPS, blob, identity, SQL auth)

Session and State Validators

Section titled “Session and State Validators”
npm CommandScriptPurpose
validate:session-statevalidate-session-state.mjsSession state JSON schema compliance
validate:session-lockvalidate-session-lock.mjsDistributed lock/claim model integrity

Quality and Cross-Reference Validators

Section titled “Quality and Cross-Reference Validators”
npm CommandScriptPurpose
lint:glob-auditvalidate-glob-audit.mjsDetect overly broad glob patterns
lint:skill-referencesvalidate-skill-references.mjsValidate skill cross-references
lint:orphaned-contentvalidate-orphaned-content.mjsDetect unreferenced skills/content
validate:docs-syncvalidate-docs-sync.mjsDocumentation file sync checks
lint:docs-freshnesscheck-docs-freshness.mjsDocumentation staleness detection
lint:version-syncvalidate-version-sync.mjsVersion consistency across files

Configuration Validators

Section titled “Configuration Validators”
npm CommandScriptPurpose
validate:vscodevalidate-vscode-config.mjsVS Code settings completeness
validate:hooksvalidate-hooks.mjsHook script structure and syntax
lint:mcp-configvalidate-mcp-config.mjsMCP server configuration validity

Code and Format Linters

Section titled “Code and Format Linters”
npm CommandToolPurpose
lint:mdmarkdownlint-cli2Markdown formatting and style
lint:linksmarkdown-link-checkURL validity in all markdown files
lint:links:docsmarkdown-link-checkURL validity in docs/ only
lint:jsonlint-json.mjsJSON/JSONC syntax validation
lint:pythonruffPython code quality (mcp/azure-pricing-mcp/)
lint:terraform-fmtterraform fmtTerraform formatting compliance
validate:terraformterraform validateTerraform validation per project

Aggregate Commands

Section titled “Aggregate Commands”
npm CommandPurpose
validate:allRun all validators (parallel Node + external)
validate:_nodeAll Node.js validators in parallel
validate:_externalAll external tool validators in parallel
validate:agentsAgent frontmatter + skills format combined

CI Workflows

Section titled “CI Workflows”

All workflows are in .github/workflows/.

WorkflowFileTriggerPurpose
Lintlint.ymlPR to main, push to mainMarkdown, artifacts, H2 sync, instructions, JSON, MCP config
Agent Validationagent-validation.ymlChanges to agents/skills/instructionsAgent frontmatter, skills format, VS Code config
Branch Enforcementbranch-enforcement.ymlPR to mainBranch naming convention and scope validation
Link Checklink-check.ymlDocs changesURL validity in documentation
Docsdocs.ymlDocs changesBuild and deploy MkDocs site
Docs Freshnessdocs-freshness.ymlScheduledDocumentation staleness detection
E2E Validatione2e-validation.ymlAgent output changesE2E pipeline structural validation
Policy Compliancepolicy-compliance-check.ymlIaC changesAzure Policy compliance checks
AVM Version Checkavm-version-check.ymlScheduledAzure Verified Module version updates
Azure Deprecation Trackerazure-deprecation-tracker.ymlScheduledTrack Azure service deprecations

Running Validations Locally

Section titled “Running Validations Locally”
Terminal window
# Run everything
npm run validate:all


# Run a specific category
npm run lint:md                    # Markdown only
npm run lint:agent-frontmatter     # Agent definitions only
npm run validate:session-state     # Session state only


# Auto-fix where supported
npm run lint:md:fix                # Fix markdown issues
npm run fix:artifact-h2 <file> --apply  # Fix artifact H2 headings
npm run lint:python:fix            # Fix Python lint issues