Harness Linter

Repository harness policy linter and fixer for agent-friendly codebases.

It ships as an npm package with prebuilt native binaries. No Go toolchain is needed in downstream repositories.

Install

npm install --save-dev @andrew-semyonov/harness-linter

Usage

npx harnesslint .
npx harnessfix .

harnessfix only applies safe mechanical fixes. Today that means creating a missing sibling CLAUDE.md containing @AGENTS.md when an AGENTS.md file exists.

Checks

harnesslint currently includes these configurable rules:

• pairing: every linted directory that has AGENTS.md must also have a sibling CLAUDE.md; every linted directory that has CLAUDE.md must also have a sibling AGENTS.md.
• claudeInclude: every linted CLAUDE.md must contain exactly @AGENTS.md after trimming whitespace. This keeps AGENTS.md canonical.
• brokenLinks: markdown links inside AGENTS.md must resolve relative to that AGENTS.md file. External http:, https:, mailto:, and same-page anchor links are ignored.

It also includes always-on repository harness checks:

• Nested guide files: README and index files are only allowed at the repository root. Directory guidance should live in AGENTS.md.
• Execution plans: files in docs exec-plan active and completed directories must use unique numeric IDs. Active plans fail lint until moved to completed; completed plans fail lint if they still have open checkboxes.
• Operational doc paths: inline-code path references in README.md, AGENTS.md, and CLAUDE.md must point to existing files or directories.

Configuration

Add harnesslint.json at the repository root:

{
  "files": {
    "ignore": [
      ".git/**",
      "thoughts/**",
      "vendor/**",
      "bin/**",
      "dist/**",
      "node_modules/**"
    ]
  },
  "linter": {
    "rules": {
      "pairing": true,
      "claudeInclude": true,
      "brokenLinks": true
    }
  }
}

By default, the ignore list is:

• .git/**
• thoughts/**
• vendor/**
• bin/**
• dist/**

If you set files.ignore, it replaces the default list, so include the default entries you still want. Rule flags can be set to false to disable a check.