agentsmd-check 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,200 @@
+# agentsmd-check
+
+[![CI](https://github.com/7y-9/agentsmd-check/actions/workflows/ci.yml/badge.svg)](https://github.com/7y-9/agentsmd-check/actions/workflows/ci.yml)
+
+<p align="center">
+  <img src="docs/assets/logo.png" alt="agentsmd-check logo" width="260">
+</p>
+
+Scan your repo. Diagnose whether `AGENTS.md` is accurate, executable, safe, and useful for coding agents.
+
+`agentsmd-check` is a local diagnostic tool and CI checker for `AGENTS.md`.
+It is not an agent framework, and it is not a general prompt management platform.
+
+> Status: early v0 CLI. The checker can be installed, run, and fail with actionable diagnostics.
+
+<p align="center">
+  <img src="docs/assets/overview.png" alt="agentsmd-check overview" width="820">
+</p>
+
+## Why
+
+`AGENTS.md` is becoming the README for AI coding agents: project overview, build commands, test commands, code style, safety notes, and repository-specific rules.
+
+The problem is that these files go stale.
+
+Common examples:
+
+- `AGENTS.md` says `npm test`, but the repo now uses `pnpm test`
+- it tells agents to run `make check`, but the `Makefile` has no `check` target
+- it references `docs/architecture.md`, but the file no longer exists
+- it asks agents to run unsafe shell patterns such as piping remote scripts into `sh`
+- it gives broad instructions but misses the actual test or style commands agents need
+
+`agentsmd-check` catches those problems before a human or coding agent follows stale instructions.
+
+## What It Checks Today
+
+Current v0 checks:
+
+| Area | What it diagnoses |
+| --- | --- |
+| File discovery | Missing root `AGENTS.md` |
+| Markdown | Headings, list items, fenced code blocks, and inline code |
+| Paths | Referenced files such as `docs/guide.md` or `.github/workflows/ci.yml` that are missing |
+| Package commands | Lockfile package manager mismatches and missing `package.json` scripts |
+| Safety | Dangerous command patterns such as `curl ... \| sh` |
+| Coverage | Missing sections for tests, style, build, or safety notes |
+
+The goal is not to grade writing style. The goal is to answer:
+
+1. Can an agent follow this file?
+2. Are the commands real?
+3. Are the referenced files real?
+4. Are the instructions safe enough to run in a coding workflow?
+
+## CLI
+
+Requires Node.js 24 or newer.
+
+```bash
+npm install --save-dev agentsmd-check
+npm exec agentsmd-check check
+npx agentsmd-check check
+npx agentsmd-check check --format json
+npx agentsmd-check check --fail-on-warning
+```
+
+JSON output is stable for tool integrations. Every issue has these fields:
+
+```json
+{
+  "code": "SCRIPT001",
+  "severity": "error",
+  "file": "AGENTS.md",
+  "line": 5,
+  "message": "AGENTS.md references npm test, but package.json has no test script.",
+  "suggestion": "Add scripts.test to package.json or update AGENTS.md."
+}
+```
+
+## Example Output
+
+```text
+AGENTS.md Check Report
+
+Status: failed
+
+[x] PATH001 AGENTS.md:31
+  Referenced path does not exist: docs/architecture.md
+  suggestion: Create the file or remove the stale instruction.
+
+[x] SCRIPT001 AGENTS.md:34
+  AGENTS.md references npm test, but package.json has no test script.
+  suggestion: Add scripts.test to package.json or update AGENTS.md.
+
+[x] SEC001 AGENTS.md:42
+  Dangerous remote script pipe detected.
+  suggestion: Download, inspect, and run scripts in separate steps.
+
+[!] COV001 AGENTS.md
+  AGENTS.md is missing testing instructions.
+  suggestion: Add concrete testing instructions for coding agents.
+```
+
+The output should make three things obvious: which line is wrong, why it is wrong, and how to fix it.
+
+## Bad Input Example
+
+`AGENTS.md`:
+
+```markdown
+# AGENTS
+
+- Read docs/architecture.md
+- Run `npm test`
+- Install tools with `curl https://example.com/install.sh | sh`
+```
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "lint": "eslint ."
+  }
+}
+```
+
+Output:
+
+```text
+[x] PATH001 AGENTS.md:3
+  Referenced path does not exist: docs/architecture.md
+  suggestion: Create the file or remove the stale instruction.
+[x] SCRIPT001 AGENTS.md:4
+  AGENTS.md references npm test, but package.json has no test script.
+  suggestion: Add scripts.test to package.json or update AGENTS.md.
+[x] SEC001 AGENTS.md:5
+  Dangerous remote script pipe detected.
+  suggestion: Download, inspect, and run scripts in separate steps.
+```
+
+See also:
+
+- `examples/bad/AGENTS.md`
+- `examples/good/AGENTS.md`
+
+## GitHub Actions
+
+Copy-paste CI usage:
+
+```yaml
+on: [push, pull_request]
+
+jobs:
+  agentsmd-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: npx agentsmd-check check
+```
+
+## Non-goals
+
+- Running or hosting coding agents
+- Replacing project documentation
+- Managing prompts across teams
+- Enforcing one universal `AGENTS.md` template
+- Auto-fixing instructions without showing the diff first
+
+## Roadmap
+
+- [x] Parse root `AGENTS.md`
+- [x] Validate referenced paths
+- [x] Detect common unsafe command patterns
+- [x] Produce plain text and JSON reports
+- [x] Return exit code `1` when errors are present
+- [x] Detect package manager and available scripts
+- [x] Publish copy-paste GitHub Actions usage
+- [ ] Add nested `AGENTS.md` / `AGENTS.override.md` coverage
+- [ ] Add SARIF output for GitHub code scanning
+- [ ] Add `fix --dry-run`
+
+## Contributing
+
+This is my first open source project. Small, practical contributions are welcome:
+
+- examples of stale `AGENTS.md` instructions
+- false positives and false negatives
+- rule ideas with a real repository example
+- documentation fixes
+
+Please keep rules concrete. A good rule should point to a real line, explain the problem, and suggest a fix.
+
+## License
+
+Apache-2.0

package/dist/check.js

@@ -0,0 +1,390 @@
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+
+                                                    
+
+                     
+               
+                     
+               
+                      
+                  
+                            
+  
+
+                             
+                                                  
+                                                   
+                                                                      
+                                                    
+  
+
+                            
+                          
+  
+
+                           
+              
+               
+                  
+          
+                   
+                     
+    
+  
+
+const AGENTS_FILE = "AGENTS.md";
+const PACKAGE_FILE = "package.json";
+
+export function parseMarkdown(markdown        )                {
+  const facts                = { headings: [], listItems: [], codeBlocks: [], inlineCode: [] };
+  const lines = markdown.split(/\r?\n/);
+  let codeBlock                                                                 ;
+
+  lines.forEach((line, index) => {
+    const lineNumber = index + 1;
+    const fence = line.match(/^\s*```\s*([A-Za-z0-9_-]*)\s*$/);
+
+    if (fence) {
+      if (codeBlock) {
+        facts.codeBlocks.push({
+          line: codeBlock.line,
+          language: codeBlock.language,
+          text: codeBlock.lines.join("\n"),
+        });
+        codeBlock = undefined;
+      } else {
+        codeBlock = { line: lineNumber + 1, language: fence[1] ?? "", lines: [] };
+      }
+      return;
+    }
+
+    if (codeBlock) {
+      codeBlock.lines.push(line);
+      return;
+    }
+
+    const heading = line.match(/^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$/);
+    if (heading) facts.headings.push({ line: lineNumber, text: heading[1] });
+
+    const listItem = line.match(/^\s*(?:[-*+]|\d+\.)\s+(.+)$/);
+    if (listItem) facts.listItems.push({ line: lineNumber, text: listItem[1] });
+
+    for (const match of line.matchAll(/`([^`\n]+)`/g)) {
+      facts.inlineCode.push({ line: lineNumber, text: match[1] });
+    }
+  });
+
+  if (codeBlock) {
+    facts.codeBlocks.push({ line: codeBlock.line, language: codeBlock.language, text: codeBlock.lines.join("\n") });
+  }
+
+  return facts;
+}
+
+export async function checkProject(root        , options               = {})                       {
+  const absoluteRoot = path.resolve(root);
+  const agentsPath = path.join(absoluteRoot, AGENTS_FILE);
+  const issues          = [];
+
+  if (!(await exists(agentsPath))) {
+    issues.push(issue({
+      code: "FILE001",
+      severity: "error",
+      file: AGENTS_FILE,
+      message: "Root AGENTS.md was not found.",
+      suggestion: "Add AGENTS.md at the repository root.",
+    }));
+    return report(absoluteRoot, issues, options);
+  }
+
+  const markdown = await readFile(agentsPath, "utf8");
+  const facts = parseMarkdown(markdown);
+
+  issues.push(...(await checkPathReferences(absoluteRoot, markdown)));
+  issues.push(...checkSafety(markdown));
+  issues.push(...(await checkPackageCommands(absoluteRoot, markdown)));
+  issues.push(...checkCoverage(facts));
+
+  return report(absoluteRoot, issues, options);
+}
+
+export function formatPlain(report             )         {
+  const lines = ["AGENTS.md Check Report", "", `Status: ${report.ok ? "ok" : "failed"}`, ""];
+
+  if (report.issues.length === 0) {
+    lines.push("[ok] no issues found");
+    return lines.join("\n");
+  }
+
+  for (const issue of report.issues) {
+    const marker = issue.severity === "error" ? "x" : issue.severity === "warning" ? "!" : "i";
+    const location = issue.line === null ? issue.file : `${issue.file}:${issue.line}`;
+    lines.push(`[${marker}] ${issue.code} ${location}`);
+    lines.push(`  ${issue.message}`);
+    if (issue.suggestion) lines.push(`  suggestion: ${issue.suggestion}`);
+  }
+
+  return lines.join("\n");
+}
+
+function report(root        , issues         , options              )              {
+  const errors = issues.filter((issue) => issue.severity === "error").length;
+  const warnings = issues.filter((issue) => issue.severity === "warning").length;
+
+  return {
+    ok: errors === 0 && (!options.failOnWarning || warnings === 0),
+    root,
+    issues,
+    stats: { errors, warnings },
+  };
+}
+
+async function checkPathReferences(root        , markdown        )                   {
+  const issues          = [];
+  const seen = new Set        ();
+  const lines = markdown.split(/\r?\n/);
+  const pathPattern = /(?:\.?\.?\/)?(?:[A-Za-z0-9_.-]+\/)+[A-Za-z0-9_.-]+\.[A-Za-z0-9]+/g;
+
+  for (const [index, line] of lines.entries()) {
+    for (const match of line.matchAll(pathPattern)) {
+      const candidate = match[0];
+      if (looksLikeUrlHost(candidate) || candidate.includes("://")) continue;
+
+      const resolved = path.resolve(root, candidate);
+      if (!isInside(root, resolved)) continue;
+
+      const key = `${index + 1}:${candidate}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+
+      if (!(await exists(resolved))) {
+        issues.push(issue({
+          code: "PATH001",
+          severity: "error",
+          file: AGENTS_FILE,
+          line: index + 1,
+          message: `Referenced path does not exist: ${candidate}`,
+          suggestion: "Create the file or remove the stale instruction.",
+        }));
+      }
+    }
+  }
+
+  return issues;
+}
+
+function checkSafety(markdown        )          {
+  const issues          = [];
+  const lines = markdown.split(/\r?\n/);
+
+  lines.forEach((line, index) => {
+    const lineNumber = index + 1;
+
+    if (/\b(?:curl|wget)\b[^|\n]*\|\s*(?:sh|bash)\b/i.test(line)) {
+      issues.push(issue({
+        code: "SEC001",
+        severity: "error",
+        file: AGENTS_FILE,
+        line: lineNumber,
+        message: "Dangerous remote script pipe detected.",
+        suggestion: "Download, inspect, and run scripts in separate steps.",
+      }));
+    }
+
+    if (/\brm\s+-[A-Za-z]*r[A-Za-z]*f[A-Za-z]*\s+["']?\/["']?(?:\s|$)/i.test(line)) {
+      issues.push(issue({
+        code: "SEC002",
+        severity: "error",
+        file: AGENTS_FILE,
+        line: lineNumber,
+        message: "Dangerous recursive root removal command detected.",
+        suggestion: "Remove this instruction or scope deletion to a safe project path.",
+      }));
+    }
+
+    if (/\b(?:token|api[_-]?key|secret|password)\s*[:=]\s*["']?[A-Za-z0-9_.-]{6,}/i.test(line)) {
+      issues.push(issue({
+        code: "SEC003",
+        severity: "error",
+        file: AGENTS_FILE,
+        line: lineNumber,
+        message: "Possible exposed credential detected.",
+        suggestion: "Remove the value and reference an environment variable instead.",
+      }));
+    }
+  });
+
+  return issues;
+}
+
+                                              
+
+                       
+                          
+                 
+               
+               
+  
+
+async function checkPackageCommands(root        , markdown        )                   {
+  const packagePath = path.join(root, PACKAGE_FILE);
+  if (!(await exists(packagePath))) return [];
+
+  let packageJson         ;
+  try {
+    packageJson = JSON.parse(await readFile(packagePath, "utf8"));
+  } catch {
+    return [
+      issue({
+        code: "PKG001",
+        severity: "error",
+        file: PACKAGE_FILE,
+        message: "package.json could not be parsed.",
+        suggestion: "Fix package.json so AGENTS.md commands can be checked.",
+      }),
+    ];
+  }
+
+  const scriptsCandidate =
+    packageJson && typeof packageJson === "object" && "scripts" in packageJson
+      ? (packageJson                         ).scripts
+      : undefined;
+  const scripts =
+    scriptsCandidate && typeof scriptsCandidate === "object" && !Array.isArray(scriptsCandidate)
+      ? (scriptsCandidate                           )
+      : {};
+  const detectedManager = await detectPackageManager(root);
+  const issues          = [];
+  const seen = new Set        ();
+
+  for (const command of extractPackageCommands(markdown)) {
+    const key = `${command.line}:${command.text}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    if (detectedManager && command.manager !== detectedManager.name) {
+      issues.push(
+        issue({
+          code: "PM001",
+          severity: "error",
+          file: AGENTS_FILE,
+          line: command.line,
+          message: `AGENTS.md references ${command.text}, but ${detectedManager.file} suggests ${detectedManager.name}.`,
+          suggestion: `Use ${detectedManager.name} for package commands or update the lockfile.`,
+        })
+      );
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(scripts, command.script)) {
+      issues.push(
+        issue({
+          code: "SCRIPT001",
+          severity: "error",
+          file: AGENTS_FILE,
+          line: command.line,
+          message: `AGENTS.md references ${command.text}, but package.json has no ${command.script} script.`,
+          suggestion: `Add scripts.${command.script} to package.json or update AGENTS.md.`,
+        })
+      );
+    }
+  }
+
+  return issues;
+}
+
+async function detectPackageManager(root        )                                                              {
+  for (const [name, file] of [
+    ["pnpm", "pnpm-lock.yaml"],
+    ["yarn", "yarn.lock"],
+    ["npm", "package-lock.json"],
+  ]         ) {
+    if (await exists(path.join(root, file))) return { name, file };
+  }
+}
+
+function extractPackageCommands(markdown        )                   {
+  const commands                   = [];
+  const lines = markdown.split(/\r?\n/);
+  const commandPattern = /\b(npm|pnpm|yarn)\s+(?:(run)\s+)?([A-Za-z0-9:_-]+)/g;
+
+  lines.forEach((line, index) => {
+    for (const match of line.matchAll(commandPattern)) {
+      const manager = match[1]                  ;
+      const script = scriptNameForCommand(manager, Boolean(match[2]), match[3]);
+      if (!script) continue;
+
+      commands.push({
+        manager,
+        script,
+        text: match[0],
+        line: index + 1,
+      });
+    }
+  });
+
+  return commands;
+}
+
+function scriptNameForCommand(manager                , hasRun         , command        )                     {
+  if (hasRun) return command;
+  if (command === "test") return "test";
+  if ((manager === "pnpm" || manager === "yarn") && ["build", "lint", "check", "format", "typecheck"].includes(command)) {
+    return command;
+  }
+}
+
+function checkCoverage(facts               )          {
+  const text = [
+    ...facts.headings.map((item) => item.text),
+    ...facts.listItems.map((item) => item.text),
+    ...facts.inlineCode.map((item) => item.text),
+    ...facts.codeBlocks.map((item) => item.text),
+  ]
+    .join("\n")
+    .toLowerCase();
+
+  const required = [
+    ["COV001", "test", "testing instructions"],
+    ["COV002", "build", "build instructions"],
+    ["COV003", "lint", "style or lint instructions"],
+    ["COV004", "safe", "safety notes"],
+  ]         ;
+
+  return required
+    .filter(([, token]) => !text.includes(token))
+    .map(([code, , label]) => issue({
+      code,
+      severity: "warning"         ,
+      file: AGENTS_FILE,
+      message: `AGENTS.md is missing ${label}.`,
+      suggestion: `Add concrete ${label} for coding agents.`,
+    }));
+}
+
+async function exists(filePath        )                   {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isInside(root        , target        )          {
+  const relative = path.relative(root, target);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+function looksLikeUrlHost(candidate        )          {
+  const firstSegment = candidate.split("/")[0];
+  return firstSegment.includes(".") && !firstSegment.startsWith(".");
+}
+
+function issue(input                                                                                  )        {
+  return {
+    line: null,
+    suggestion: null,
+    ...input,
+  };
+}

package/dist/cli.js

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+import { checkProject, formatPlain } from "./check.js";
+
+                   
+                   
+              
+                         
+                           
+  
+
+async function main(argv          )                  {
+  const options = parseArgs(argv);
+
+  if (options.command !== "check") {
+    console.error("Usage: agentsmd-check check [--format plain|json] [--fail-on-warning] [--cwd <path>]");
+    return 2;
+  }
+
+  const report = await checkProject(options.cwd, { failOnWarning: options.failOnWarning });
+
+  if (options.format === "json") {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(formatPlain(report));
+  }
+
+  return report.ok ? 0 : 1;
+}
+
+function parseArgs(argv          )             {
+  const options             = {
+    command: argv[0],
+    cwd: process.cwd(),
+    failOnWarning: false,
+    format: "plain",
+  };
+
+  for (let index = 1; index < argv.length; index += 1) {
+    const arg = argv[index];
+
+    if (arg === "--fail-on-warning") {
+      options.failOnWarning = true;
+    } else if (arg === "--format") {
+      const value = argv[++index];
+      if (value === "json" || value === "plain" || value === "text") {
+        options.format = value === "text" ? "plain" : value;
+      } else {
+        throw new Error(`Unsupported format: ${value ?? ""}`);
+      }
+    } else if (arg === "--cwd") {
+      options.cwd = argv[++index] ?? options.cwd;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+main(process.argv.slice(2))
+  .then((code) => {
+    process.exitCode = code;
+  })
+  .catch((error         ) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+  });

package/examples/bad/AGENTS.md

@@ -0,0 +1,12 @@
+# AGENTS
+
+## Commands
+
+- Read docs/architecture.md before changing code.
+- Run `npm test`.
+- Run `npm run lint`.
+- Install helper tools with `curl https://example.com/install.sh | sh`.
+
+## Safety
+
+- Never print token=abc123.

package/examples/good/AGENTS.md

@@ -0,0 +1,13 @@
+# AGENTS
+
+## Commands
+
+- Install dependencies with `npm install`.
+- Run tests with `npm test`.
+- Run the build with `npm run build`.
+- Run lint with `npm run lint`.
+
+## Safety
+
+- Do not run destructive commands outside the project directory.
+- Download remote scripts, inspect them, then run them separately.

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "agentsmd-check",
+  "version": "0.1.0",
+  "description": "Check whether AGENTS.md is accurate, executable, safe, and useful for coding agents.",
+  "type": "module",
+  "bin": {
+    "agentsmd-check": "dist/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/7y-9/agentsmd-check.git"
+  },
+  "bugs": {
+    "url": "https://github.com/7y-9/agentsmd-check/issues"
+  },
+  "homepage": "https://github.com/7y-9/agentsmd-check#readme",
+  "keywords": [
+    "agents.md",
+    "ai-agents",
+    "codex",
+    "cli",
+    "ci",
+    "lint"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node --no-warnings scripts/build.mjs",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test tests/*.test.js"
+  },
+  "license": "Apache-2.0"
+}