{"_id":"@agentwares/agentsmd-lint","_rev":"2-86ebd8f7a7a143d6f28092b09100616e","name":"@agentwares/agentsmd-lint","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@agentwares/agentsmd-lint","version":"0.1.0","keywords":["agents.md","claude.md","cursorrules","lint","linter","coding-agents","claude-code","agent-readiness","badge"],"license":"MIT","_id":"@agentwares/agentsmd-lint@0.1.0","maintainers":[{"name":"umerbukhari","email":"umer.bukhari@gmail.com"}],"homepage":"https://github.com/agentwares/agentwares/tree/main/assets/agents-md-lint#readme","bugs":{"url":"https://github.com/agentwares/agentwares/issues"},"bin":{"agentsmd-lint":"dist/cli.js"},"dist":{"shasum":"df4343c95ed22fb2f180f9f30d3b23368ae7da9f","tarball":"https://registry.npmjs.org/@agentwares/agentsmd-lint/-/agentsmd-lint-0.1.0.tgz","fileCount":14,"integrity":"sha512-A81jiayBTQY/kP0xZ1vTRnXbZUWOrMTs5Mxqi1b/Sf8860s2D0dHR9jEBxmJtg4KwXBpopxIfYlAWqh2GhLUjw==","signatures":[{"sig":"MEYCIQDlTR68pka+juN3RCNDpXlVrJhNDfcr0XETOLIuLGV6BAIhAJBu0sidTInll6K48x8ra17ISIy1wUcA/nOv+CVAJTrS","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":503897},"main":"./dist/index.js","type":"module","_from":"file:agentwares-agentsmd-lint-0.1.0.tgz","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./worker":{"types":"./dist/github/worker.d.ts","import":"./dist/github/worker.js"}},"scripts":{"lint":"eslint src","self":"node dist/cli.js ../..","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"_npmUser":{"name":"umerbukhari","email":"umer.bukhari@gmail.com"},"_resolved":"/private/var/folders/2p/2j2wcvfs4wz6v0nfr4h455k40000gn/T/82f795337b88a98d264a558bbef0e93b/agentwares-agentsmd-lint-0.1.0.tgz","_integrity":"sha512-A81jiayBTQY/kP0xZ1vTRnXbZUWOrMTs5Mxqi1b/Sf8860s2D0dHR9jEBxmJtg4KwXBpopxIfYlAWqh2GhLUjw==","repository":{"url":"git+https://github.com/agentwares/agentwares.git","type":"git","directory":"assets/agents-md-lint"},"_npmVersion":"10.9.8","description":"Lint AGENTS.md / CLAUDE.md / .cursorrules for stale commands, dead paths, contradictions and missing test or dev-env instructions. Emits an agent-readiness score and an SVG badge. No LLM, no telemetry, no account.","directories":{},"sideEffects":false,"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@agentwares/badge":"^0.1.0"},"_npmOperationalInternal":{"tmp":"tmp/agentsmd-lint_0.1.0_1788483434903_0.6709051935771473","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"_id":"@agentwares/agentsmd-lint@0.1.1","bin":{"agentsmd-lint":"dist/cli.js"},"bugs":{"url":"https://github.com/agentwares/agentsmd-lint/issues"},"dist":{"shasum":"698eaedae8d889c3364d7c922acf6d683ce8f2eb","tarball":"https://registry.npmjs.org/@agentwares/agentsmd-lint/-/agentsmd-lint-0.1.1.tgz","fileCount":14,"integrity":"sha512-cTGkXLEUOGL6ltNn83FR3USG1Hfw3Y1nafT1xa3tObkIMciDd5RS/gPrQ6++rri0SMJ9RRwSyl9FXJ6qKg+/7g==","signatures":[{"sig":"MEUCIQD7DOcyBFtazQFTeic8QYRY8MELsHkDadASy/fS3kfMRgIgPFmQzwKlJJU190vTpR69qIyc3UM9d4oag1D8bv+6Ay8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"},{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC4jxWfXcXHncTxGfvthJWIHFKERnPH7kODKunLw+OPPAIhAPVp1MNhn9Xj5Fzo+mI2NFW6yvFceY5A6Ylvh0pdQ775"}],"unpackedSize":503920},"main":"./dist/index.js","name":"@agentwares/agentsmd-lint","type":"module","_from":"file:agentwares-agentsmd-lint-0.1.1.tgz","types":"./dist/index.d.ts","engines":{"node":">=20"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./worker":{"types":"./dist/github/worker.d.ts","import":"./dist/github/worker.js"}},"license":"MIT","scripts":{"lint":"eslint src","self":"node dist/cli.js ../..","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit"},"version":"0.1.1","_npmUser":{"name":"umerbukhari","email":"umer.bukhari@gmail.com"},"homepage":"https://github.com/agentwares/agentsmd-lint#readme","keywords":["agents.md","claude.md","cursorrules","lint","linter","coding-agents","claude-code","agent-readiness","badge"],"_resolved":"/private/var/folders/2p/2j2wcvfs4wz6v0nfr4h455k40000gn/T/2c439db50e3a83c40a030e9ab37a5b82/agentwares-agentsmd-lint-0.1.1.tgz","_integrity":"sha512-cTGkXLEUOGL6ltNn83FR3USG1Hfw3Y1nafT1xa3tObkIMciDd5RS/gPrQ6++rri0SMJ9RRwSyl9FXJ6qKg+/7g==","repository":{"url":"git+https://github.com/agentwares/agentsmd-lint.git","type":"git"},"_npmVersion":"10.9.8","description":"Lint AGENTS.md / CLAUDE.md / .cursorrules for stale commands, dead paths, contradictions and missing test or dev-env instructions. Emits an agent-readiness score and an SVG badge. No LLM, no telemetry, no account.","directories":{},"maintainers":[{"name":"umerbukhari","email":"umer.bukhari@gmail.com"}],"sideEffects":false,"_nodeVersion":"22.23.2","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"@agentwares/badge":"^0.1.0"},"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agentsmd-lint_0.1.1_1788807057038_0.6765225830303414"}}},"time":{"created":"2026-09-04T00:57:14.707Z","modified":"2026-09-07T18:50:57.297Z","0.1.0":"2026-09-04T00:57:15.119Z","0.1.1":"2026-09-07T18:50:57.131Z"},"bugs":{"url":"https://github.com/agentwares/agentsmd-lint/issues"},"license":"MIT","homepage":"https://github.com/agentwares/agentsmd-lint#readme","keywords":["agents.md","claude.md","cursorrules","lint","linter","coding-agents","claude-code","agent-readiness","badge"],"repository":{"url":"git+https://github.com/agentwares/agentsmd-lint.git","type":"git"},"description":"Lint AGENTS.md / CLAUDE.md / .cursorrules for stale commands, dead paths, contradictions and missing test or dev-env instructions. Emits an agent-readiness score and an SVG badge. No LLM, no telemetry, no account.","maintainers":[{"name":"umerbukhari","email":"umer.bukhari@gmail.com"}],"readme":"# agentsmd-lint\n\nLint `AGENTS.md`, `CLAUDE.md`, `.cursorrules` (and `GEMINI.md`, `.cursor/rules/*.mdc`, `.github/copilot-instructions.md`, `.windsurfrules`, `.clinerules`) **against the repo they describe**. Finds the things that quietly send coding agents down the wrong path, then scores the repo and renders an agent-readiness badge.\n\n```bash\nnpx @agentwares/agentsmd-lint # lint the current repo, print the report, exit 1 on errors\n```\n\n```\nagentsmd-lint v0.1.0 — AGENTS.md, CLAUDE.md, .cursorrules\nscore 20/100 (F) — 10 errors, 1 warning\n\nCLAUDE.md:3 error contradiction CLAUDE.md says Node 18, but package.json engines.node says Node 22\n fix: Use Node 22 everywhere (engines.node / .nvmrc are the source of truth).\nCLAUDE.md:8 error stale-command `pnpm lint:fix` runs script \"lint:fix\", which is not defined in package.json\n fix: Add a \"lint:fix\" script to package.json or change the instruction to an existing script (dev, build, test, lint).\nCLAUDE.md:19 error dead-path `src/server/index.ts` does not exist in the repo\n fix: Update the path (the file was probably moved or renamed) or delete the reference.\n…\n```\n\nNo LLM. No network. No account. No telemetry (the only \"phone home\" is an opt-in `--star` line that prints a link).\n\n## What it checks\n\n| Rule | Severity | What it catches |\n| ----------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `stale-command` | error | `npm run x` / `pnpm x` / `yarn x` / `bun run x` scripts missing from `package.json` (workspace-aware: `pnpm --filter pkg x`, `-r`), `make x` targets missing from the Makefile, `turbo x` tasks, `just x` recipes |\n| `unknown-workspace-package` | warning | `pnpm --filter ` where `` is not a workspace package |\n| `dead-path` | error | inline-code paths and relative links (`src/foo.ts`, `docs/x.md`, `packages/*`) that do not exist |\n| `contradiction` | error | different package managers across files (or vs the lockfile), different test runners (vitest vs jest, pytest vs unittest), different Node majors (vs `engines.node` / `.nvmrc`) |\n| `lockfile-mismatch` | warning | every file says `npm`, the repo has `pnpm-lock.yaml` |\n| `missing-test-instructions`, `missing-dev-env-instructions` | error | no test command, no install/dev/env-file instruction anywhere |\n| `no-instruction-file` | error | nothing for an agent to read |\n\nNegated prose is ignored (`Do not run \\`npm install\\``does not count as \"uses npm\"), build-output and`.env*`paths are skipped,`/api/health`-style tokens are treated as routes, `path/to/x` as placeholders. A bare name with no directory (`llms.txt`, `settings.json`) is only flagged when the repo really has one somewhere — otherwise it is prose about a concept, not a path — and the fix then names the path you probably meant.\n\n**Score** = 100 − capped deductions (stale 10 each ≤ 40, dead path 5 ≤ 30, contradiction 15 ≤ 30, missing tests 15, missing dev-env 10, warnings 5). Grades: A ≥ 90, B ≥ 75, C ≥ 60, D ≥ 40, F. Weights are in `src/score.ts`.\n\n## CLI\n\n```\nagentsmd-lint [dir] [--format text|json|markdown|github] [--badge out.svg] [--min-score N]\n [--no-fail] [--disable rule,rule] [--file extra.md] [--star]\n```\n\n- `--badge agent-readiness.svg` writes the badge locally (rendered with `@agentwares/badge`, inlined into the bundle — zero runtime dependencies).\n- `--format markdown` is the PR-comment body; `--format github` prints workflow annotations.\n- Exit codes: `0` clean (or `--no-fail`), `1` errors or below `--min-score`, `2` usage error.\n\nProgrammatic:\n\n```ts\nimport {\n lintDir,\n lint,\n memoryReader,\n renderReadinessBadge,\n formatMarkdown,\n} from \"@agentwares/agentsmd-lint\";\n\nconst report = await lintDir(\".\");\nreport.score; // { value: 85, grade: \"B\", status: \"degraded\", breakdown: [...] }\nreport.findings; // [{ rule, severity, file, line, message, fix, subject }]\nrenderReadinessBadge(report.score); // SVG string\nawait lint(memoryReader({ \"AGENTS.md\": \"...\", \"package.json\": \"{}\" })); // any RepoReader\n```\n\n## Badge\n\nThe CLI writes the SVG; READMEs and PR comments use the hosted stateless badge (no data stored, nothing tracked):\n\n```markdown\n![agent-ready](https://agentwares-readiness.vercel.app/badge/agents-md.svg?score=85&grade=B)\n```\n\n## GitHub Action\n\n```yaml\n# .github/workflows/agentsmd-lint.yml\nname: agentsmd-lint\non: [pull_request]\npermissions:\n contents: read\n pull-requests: write\njobs:\n lint:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: agentwares/agentsmd-lint@main\n with:\n min-score: 60 # optional\n fail-on-error: false # optional\n```\n\nPosts one sticky comment per PR (updated on every push), writes the report to the job summary, emits annotations, and exposes `score` / `grade` outputs. Nothing leaves the runner except the comment.\n\n## GitHub App (hosted, free for public repos)\n\nThe same linter as a GitHub App so repos need no workflow file. The webhook handler is Web-standard (`src/github/webhook.ts`: verifies `X-Hub-Signature-256`, mints the installation token with an RS256 JWT via Web Crypto, reads the PR head through the contents API, upserts the sticky comment) and ships as a Cloudflare Worker entry (`src/github/worker.ts`, `wrangler.toml`) and as a Vercel route in the readiness-scorer app (`/api/agents-md-lint/webhook`).\n\nRegistration needs the org owner (not done yet — see `docs/reports/A1.md`):\n\n1. GitHub → Settings → Developer settings → GitHub Apps → **New GitHub App**: name `agentsmd-lint`, webhook URL `https://agentwares-readiness.vercel.app/api/agents-md-lint/webhook`, a webhook secret.\n2. Permissions: Repository → Contents **Read**, Pull requests **Write**, Metadata **Read**. Subscribe to **Pull request**.\n3. Generate a private key; set `AGENTSMD_LINT_APP_ID`, `AGENTSMD_LINT_PRIVATE_KEY` (PEM, PKCS#1 or PKCS#8; `\\n`-escaped is fine), `AGENTSMD_LINT_WEBHOOK_SECRET` on the Vercel project (or `GITHUB_APP_*` for the Worker), redeploy.\n4. Make the App public, install it on a repo, open a PR: the comment appears within seconds.\n\n## Fixtures\n\n`fixtures/seeded/` is a small repo with every problem seeded (3 stale commands, 3 dead paths, 4 contradictions, 1 unknown workspace package → 20/100 F); `fixtures/clean/` scores 100. `src/lint.test.ts` asserts both.\n\n## Development\n\n```bash\npnpm --filter agentsmd-lint build && pnpm --filter agentsmd-lint test\nnode assets/agents-md-lint/dist/cli.js . # lint this monorepo\n```\n\n---\n\nFree forever. Want a live status badge for the agent or MCP server the repo ships? That is [agentcheck](https://agentwares-agentcheck.vercel.app).\n","readmeFilename":"README.md"}