Check Catalog

Harnix ships with 8 built-in checks grouped into 6 categories. Each check produces a score between 0 and 1.0, which is then weighted by its tier during overall scoring. The table below summarizes every check; detailed descriptions and scoring rules follow.

Active checks

Name	Check ID	Category	Tier	Applies to
Agents guidance	agents-md	agent-readiness	critical	all
Agent skills	agent-skills	agent-readiness	important	all
CI pipeline	ci-pipeline	quality-gates	important	software
Root README	root-readme	documentation	critical	all
Documentation	documentation	documentation	important	all
Repo structure	repo-structure	infrastructure	important	software
Source of truth	source-of-truth	organization	important	all
Testing provision	testing-provision	quality	important	software

Check details

Agents guidance

agent-readiness critical all repositories

Detects whether the repository provides agent guidance via a root-level AGENTS.md or CLAUDE.md file. The file should contain repo-specific constraints, non-obvious gotchas, paths or conventions that agents would otherwise miss.

What it checks

• Presence of AGENTS.md or CLAUDE.md at the repository root
• Content length and substance of the guidance file

Scoring

Condition	Score
No AGENTS found	0
Suspiciously empty file (0 chars)	0.2
Suspiciously long file (10,000+ chars)	0.2
File is getting long (5,000 ~ 10,000 chars)	0.4
File is getting short (less than 120 chars)	0.4
File is a bit long, but still fine (3,000 ~ 5,000 chars)	0.6
File is a bit brief, but still fine (120 ~ 1,000 chars)	0.8
File has substantive content and not too long (1,000 ~ 3,000 chars)	1.0

Agent skills

agent-readiness important all repositories

Detects skills in supported roots and validates that each skill conforms to the Agent Skills specification. Skills must contain a SKILL.md file with proper frontmatter and body content. Hidden Markdown comments in SKILL.md are flagged as a security risk because they are not visibly rendered to the reader.

What it checks

• Presence of skill roots (skills/, .skills/, .claude/skills/, .codex/skills/, .agent/skills/, .github/skills/)
• Each skill has a valid SKILL.md with frontmatter and body content
• Subdirectories are restricted to scripts/, references/, and assets/
• Hidden Markdown comments in SKILL.md outside fenced code blocks (flagged as security risk)

Scoring

Condition	Score
No skill directories found	0
Skills found with mixed compliance and no security flags	0.5–0.8
All skills compliant, no hidden Markdown comments	1.0
Hidden Markdown comments detected	Penalty applied (reduces score)

The score is 0 when no skill directories are found, and ranges from 0.2 to 1.0 based on the ratio of compliant skills and the absence of security violations.

CI pipeline

quality-gates important software repositories

Detects whether the repository has a CI/CD pipeline configured. Supports GitHub Actions, GitLab CI, CircleCI, Jenkins, Travis CI, and Azure Pipelines.

What it checks

• Presence of CI configuration files or directories (e.g., .github/workflows/, .gitlab-ci.yml, .circleci/, Jenkinsfile, .travis.yml, azure-pipelines.yml)

Scoring

Condition	Score
No CI configuration detected	0
At least one CI system detected	1.0

Root README

documentation critical all repositories

Checks for a substantive root README.md or README.txt file. The root README should be the fastest onboarding artifact in the repository and cover how to get started, how to run the project, and how to verify changes.

What it checks

• Presence of README.md or README.txt at the repository root
• Whether the README has substantive body content instead of a placeholder heading
• Whether the README includes setup, usage, and testing or troubleshooting guidance

Scoring

Condition	Score
No supported root README found	0
Root README exists but is only a placeholder	0.3
Substantive root README	+0.4
Setup/install guidance detected	+0.1
Usage/run guidance detected	+0.1
Testing/troubleshooting guidance detected	+0.1

The components are summed and capped at 1.0.

Documentation

documentation important all repositories

Checks for durable documentation roots such as docs/, specs/, and prds/. This check focuses on whether the repository has a canonical long-form documentation layer, separate from the root README.

What it checks

• Presence of supported documentation roots: docs/, specs/, prds/
• Whether those roots contain supported documentation files (.md, .mdx, .txt, .rst, .adoc, .yaml, .yml, .json, .toml)
• Whether at least one matched documentation file contains substantive content

Scoring

Condition	Score
No supported documentation roots found	0
Documentation roots exist but contain no supported documentation files	0.2
Documentation roots exist but only placeholder docs were detected	0.4
At least one substantive doc exists under docs/, specs/, or prds/	1.0

Repo structure

infrastructure important software repositories

Evaluates the repository’s source code organization, separation of concerns, and monorepo tooling. Well-structured repositories keep root clutter low, organize source code in dedicated directories, and configure workspaces when using submodules.

What it checks

• Source code directories (src/, lib/, packages/, apps/, modules/, crates/)
• Root file ratio (percentage of files at the repository root vs. subdirectories)
• Monorepo signals (.gitmodules, workspace configurations in package.json, pnpm-workspace.yaml, etc.)
• Presence of any meaningful subdirectory structure

Scoring

Component	Points
Source code directories detected	+0.35
Root file ratio < 30%	+0.25
Root file ratio 30–50%	+0.15
Monorepo tooling with workspace config	+0.25
Submodules without workspace config	+0.15
Any subdirectories exist	+0.15

Components are summed for a maximum score of 1.0.

Source of truth

organization important all repositories

Detects single-source-of-truth violations by scanning for duplicate definitions across six semantic groups. When the same kind of configuration, policy, or specification appears in multiple locations, it signals organizational drift and maintenance risk.

What it checks

Six semantic groups are evaluated for duplication:

1. Legal / Policies — license files, terms, privacy policies
2. Styling / Brand — style guides, brand assets, design tokens
3. Configuration — .config files, .env files, settings directories
4. Architecture — specs, ADRs, decision records
5. API Specs — OpenAPI / Swagger definitions
6. Database Config — migration files, schema definitions

Historical snapshots under archive/ and legacy/ are excluded from this check. Configuration files are also treated as scoped (not duplicated) when the same filename appears once per project root in a monorepo.

Scoring

Condition	Score
No violations detected	1.0
One violation	0.75
Two violations	0.50
Three violations	0.25
Four or more violations	0

Each violation reduces the score by 0.25.

Testing provision

quality important software repositories

Evaluates whether the repository has runnable tests, properly isolated test directories, and testing documentation. Repositories that separate tests into dedicated directories and document their testing approach receive the highest scores.

What it checks

• Presence of test files (patterns like *.test.ts, *.spec.ts, *.test.js, etc.)
• Test isolation in dedicated directories (test/, tests/, __tests__/)
• Testing documentation in README or standalone test docs (e.g., test*.md)

Scoring

Component	Points
Test files exist	+0.6
Tests isolated in dedicated directories	+0.25
Testing documentation present	+0.15

Components are summed for a maximum score of 1.0.

Filter by check ID

Use check IDs with CLI flags to run or skip specific checks:

harnix scan . --only agents-md
harnix scan . --skip ci-pipeline
harnix scan . --only agents-md,root-readme,documentation
harnix scan . --skip repo-structure,source-of-truth