Block the merge, not the author.

GitHub Action

Five lines of your own plus the checkout. The Action is a composite step that runs the asitis bundle committed in its own repository, so the lint runs with no package download. It needs Node 22.13 or later; actions/setup-node makes that explicit instead of trusting the runner image.

name: Steering files
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  asitis:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - uses: Katta041/asitis-agent-tools@v0.3.0

Findings are printed as workflow commands (::error, ::warning, ::notice), which GitHub shows as annotations on the changed lines in the Files changed tab and in the job summary. The job fails when a finding is at or above fail-on, which is error by default.

Pinning: the snippets use version tags so they read clearly. If your organisation pins actions to a commit SHA, as GitHub's hardening guide recommends, pin these the same way; the Action's README carries the SHA for each release.

Code scanning with SARIF

The Action writes asitis.sarif by default; set upload-sarif to send it to code scanning. Findings then appear under Security, Code scanning, each with a link to its rule page and a severity GitHub can sort on. Suppressed findings stay in the file, marked, so a reviewer can see what was silenced. Code scanning has to be on: every public repository has it, a private one needs GitHub Code Security. The upload runs with continue-on-error, so a 403 shows as a warning and the job result still comes from the lint.

name: Steering files
on:
  pull_request:
  push:
    branches: [main]
permissions:
  contents: read
jobs:
  asitis:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
      actions: read # needed on private repos; harmless on public ones
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with:
          node-version: 22
      - uses: Katta041/asitis-agent-tools@v0.3.0
        with:
          fail-on: warning
          include: skills,config
          upload-sarif: ${{ github.event_name == 'push' }}

Only this job needs security-events: write; the lint itself needs contents: read and nothing else. Pull requests from forks never get that permission, which is why the example uploads on pushes to main only; annotations still appear on every pull request. The upload is GitHub's own upload-sarif action, pinned inside the Action, and it is the only network traffic in the job.

Inputs and outputs

Outputs: exit-code (0 clean, 1 findings at or above fail-on, 2 a setup problem, 3 a bug), errors, warnings and notes (counts of unsuppressed findings) and sarif-file (the path written). To read the numbers without failing the job, set fail-on: never.

pre-commit, lefthook and husky

With pre-commit, the hook runs the committed bundle against the staged steering files only, so it is fast and needs no install step beyond Node:

repos:
  - repo: https://github.com/Katta041/asitis-agent-tools
    rev: v0.3.0
    hooks:
      - id: asitis-lint

The hook's files pattern covers CLAUDE.md, AGENTS.md, GEMINI.md, SKILL.md, Claude Code rules, subagents and memory files, Cursor .mdc rules and Copilot instructions. It exits 1 on an error-level finding; add args: [--fail-on, warning] to be stricter.

Without pre-commit, the npx form works in any hook runner. Pin the version in the command, as in every MCP config, so a hook never runs whatever was published last:

pre-commit:
  commands:
    asitis:
      glob: "{CLAUDE.md,AGENTS.md,GEMINI.md,**/CLAUDE.md,**/AGENTS.md,**/SKILL.md,.claude/**/*.md,.cursor/rules/*.mdc,.github/copilot-instructions.md}"
      run: npx -y -p @asitis/mcp@0.3.0 asitis lint {staged_files}

# .husky/pre-commit
npx -y -p @asitis/mcp@0.3.0 asitis lint

GitLab CI and any other runner

Everything the Action does is one command, so any runner with Node 22.13 or later can run it. This GitLab job writes the SARIF file first (kept as an artifact whatever happens), then runs the lint again for the exit code:

asitis:
  image: node:22
  script:
    - npx -y -p @asitis/mcp@0.3.0 asitis lint --format sarif > asitis.sarif || true
    - npx -y -p @asitis/mcp@0.3.0 asitis lint
  artifacts:
    when: always
    paths: [asitis.sarif]

The same command with the three flags you are most likely to want:

npx -y -p @asitis/mcp@0.3.0 asitis lint --fail-on warning
npx -y -p @asitis/mcp@0.3.0 asitis lint --format json > asitis.json
npx -y -p @asitis/mcp@0.3.0 asitis lint --format github

Output formats: text (one finding per line, path:line:col severity rule-id message, then a summary), json (a stable schema, schemaVersion: 1, with every finding's fingerprint and any fix), sarif (2.1.0, with the rule list, help links and fingerprints) and github (workflow commands, escaped so file text can never start one).

Exit codes

A partial lint never looks like a clean one: if the run stops at the file limit or the time budget, the exit code is 2 with a line saying so.

Adopting it on an existing repository

Write a baseline once, commit it, and only new findings fail the build. Fingerprints are built from the rule, the path and the normalised line text, so they survive edits above the line and a CRLF to LF conversion; a new copy of a baselined line still fires.

npx -y -p @asitis/mcp@0.3.0 asitis lint --format json --write-baseline > .asitis-baseline.json
git add .asitis-baseline.json

Then pass baseline: .asitis-baseline.json to the Action, or --baseline .asitis-baseline.json to the CLI. Baselined findings are counted as suppressed in every summary. To tune individual rules instead, see .asitisrc.json on the plugin page.

What it reads

• Markdown steering files under the root, and .asitisrc.json when it exists. Up to 1,000 files; pass paths to lint more.
• With include: skills, scripts inside folders that contain a SKILL.md, at most 1 MB each, allowlisted extensions only; binaries by their first 4 bytes. Findings quote at most 80 characters, after redaction.
• With include: config, the named agent config files: .claude/settings.json, .mcp.json, .cursor/mcp.json, .vscode/mcp.json, .gemini/settings.json. Values are never printed, only key paths and a redacted preview. .claude/settings.local.json needs config-local.
• Never: .env*, .git/, node_modules/, anything outside the root, or anything in your home folder.

Source and issues: https://github.com/Katta041/asitis-agent-tools. The Action's own self-test runs it on a clean and a dirty fixture on Ubuntu and Windows before every release.