HADS Validator Action

Validate Markdown files against the Human-AI Document Standard in your CI pipeline.

---

Quick start

- uses: catcam/hads-action@v1

That's it. Add it to any workflow step and it validates all **/*.md files in your repo.

---

Full example

# .github/workflows/hads.yml
name: HADS Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: catcam/hads-action@v1
        with:
          paths: "**/*.md"
          fail_on_violation: "true"

---

Inputs

Input	Description	Default
paths	Glob pattern of files to validate	**/*.md
fail_on_violation	Fail CI if any violations are found	true
add_badge	Auto-insert HADS badge into README on success	true

Set fail_on_violation: "false" to run in report-only mode — violations are printed but CI passes.

Automatic badge

When add_badge: "true" (default), the action automatically inserts this badge into your README.md the first time validation passes:

The commit message includes [skip ci] so it won't trigger another workflow run. Requires permissions: contents: write in your workflow:

jobs:
  validate:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: catcam/hads-action@v1

---

What it checks

Check	Description
H1 title	Document must have a top-level # Title heading
Version	**Version X.Y.Z** declaration required near the top
AI manifest	AI READING INSTRUCTION section must be present before content
[BUG] fields	Every **[BUG]** block must contain symptom and fix fields
Tag formatting	Warns on unformatted tags that should use **[TAG]** syntax

---

About HADS

HADS (Human-AI Document Standard) is a lightweight Markdown convention that makes technical documentation work equally well for humans and AI language models.

• Specification
• Examples
• Full documentation
• Position paper — DOI: 10.5281/zenodo.19288202

---

License

MIT