Central reference for all validation scripts, linting commands, git hooks, and CI workflows.
Jump to: Architecture ·
Lefthook Hooks ·
Validation Scripts ·
CI Workflows ·
Running Locally
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
Pre-commit — validates staged files only (fast, file-type scoped, parallel)Pre-push — validates all changed files vs main (domain-scoped, parallel)CI — validates the full repository on every PR and push to main
All hooks are defined in lefthook.yml at the repository root.
Hook Trigger (glob) Purpose markdown-lint*.mdmarkdownlint on staged markdown files link-checksite/src/content/docs/**/*.{md,mdx}Verify URLs in staged docs files h2-syncSKILL.md, azure-artifacts files Check H2 heading sync across sources artifact-validationagent-output/**/*.mdValidate artifact H2 structure against templates agents**/*.agent.md, **/*.prompt.mdAgent frontmatter, model alignment, body size instructions**/*.instructions.md, agents, skillsInstruction frontmatter and cross-reference validity secrets-baseline(all staged files) gitleaks secret scan (soft-skip if not installed) python-linttools/mcp-servers/**/*.pyRuff linter on Python files terraform-fmt*.tfTerraform formatting check terraform-validate*.tfTerraform validation per project iac-security-baselineinfra/bicep/**/*.bicep, infra/terraform/**/*.tfTLS 1.2, HTTPS-only, no public blob, managed identity
Hook Purpose 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
All scripts are in the tools/scripts/ directory. Run via npm run <command>.
npm Command Script Purpose validate:agentsvalidate-agents.mjsAgent frontmatter, body size, model alignment validate:skillsvalidate-skills.mjsSkill format, affinity, references, stale refs 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:workflow-graphvalidate-workflow-graph.mjsDAG integrity (no orphans, no cycles)
npm Command Script Purpose validate:artifactsvalidate-artifacts.mjsH2 sync, template compliance, and auto-fix (with --fix) e2e:validatevalidate-e2e-step.mjsE2E pipeline structural validation e2e:benchmarkbenchmark-e2e.mjs8-dimension benchmark scoring
npm Command Script Purpose lint:governance-refsvalidate-governance-refs.mjsGovernance guardrails integrity validate:no-hardcoded-countsvalidate-no-hardcoded-counts.mjsPrevent hardcoded entity counts 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)
npm Command Script Purpose validate:session-statevalidate-session-state.mjsSchema validation + deprecated lock/claim field detection
npm Command Script Purpose lint:glob-auditvalidate-glob-audit.mjsDetect overly broad glob patterns lint:orphaned-contentvalidate-orphaned-content.mjsDetect unreferenced skills/content lint:docs-freshnesscheck-docs-freshness.mjsDocumentation staleness detection lint:version-syncvalidate-version-sync.mjsVersion consistency across files
npm Command Script Purpose validate:vscodevalidate-vscode-config.mjsVS Code settings completeness validate:hooksvalidate-hooks.mjsHook script structure and syntax test:hookstest-hooks.shHook integration tests (bats) lint:mcp-configvalidate-mcp-config.mjsMCP server configuration validity
npm Command Tool Purpose lint:mdmarkdownlint-cli2 Markdown formatting and style lint:linksmarkdown-link-check URL validity in all markdown files lint:links:docsmarkdown-link-check URL validity in site docs lint:jsonlint-json.mjsJSON/JSONC syntax validation lint:pythonruff Python code quality (tools/mcp-servers/azure-pricing/) lint:terraform-fmtterraform fmt Terraform formatting compliance validate:terraformterraform validate Terraform validation per project
npm Command Purpose validate:allRun all validators (parallel Node + external) validate:_nodeAll Node.js validators in parallel validate:_externalAll external tool validators in parallel validate:agentsAgent frontmatter, body, model alignment validate:artifactsH2 sync, template compliance, auto-fix validate:skillsSkill format, affinity, references, stale audit:quarterlyQuarterly context audit checks
All workflows are in .github/workflows/.
Workflow File Trigger Purpose CI ci.ymlPR to main, push to main Full validation suite (markdown, agents, skills, hooks, gitleaks, bats tests, MCP, VS Code config) Branch Enforcement branch-enforcement.ymlPR to main Branch naming convention and scope validation Link Check link-check.ymlDocs changes URL validity in documentation Docs docs.ymlDocs changes Build and deploy Astro Starlight site E2E Validation e2e-validation.ymlAgent output changes E2E pipeline structural validation Weekly Maintenance weekly-maintenance.ymlScheduled (weekly) Freshness audits, orphaned content, glob audit Azure Deprecation Tracker azure-deprecation-tracker.ymlScheduled Track Azure service deprecations
# Run a specific category
npm run lint:md # Markdown only
npm run validate:agents # 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:artifacts -- <file> --apply # Fix artifact H2 headings
npm run lint:python:fix # Fix Python lint issues
