@yegor256/dogent 0.0.1

package/LICENSE.txt

@@ -0,0 +1,21 @@
+(The MIT License)
+
+Copyright (c) 2026 Yegor Bugayenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the 'Software'), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,128 @@
+# Dogmatic Linter for Agent Skills and Manifestos
+
+[![dogent](https://github.com/yegor256/dogent/actions/workflows/dogent.yml/badge.svg)](https://github.com/yegor256/dogent/actions/workflows/dogent.yml)
+[![PDD status](https://www.0pdd.com/svg?name=yegor256/dogent)](https://www.0pdd.com/p?name=yegor256/dogent)
+[![License](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/yegor256/dogent/blob/master/LICENSE.txt)
+[![NPM version](https://badge.fury.io/js/@yegor256%2Fdogent.svg)](https://badge.fury.io/js/@yegor256%2Fdogent)
+
+A strict, opinionated linter for agentic manifesto files
+  such as `SKILL.md`, `CLAUDE.md`, and `AGENTS.md`.
+
+These files instruct AI agents.
+Vague, bloated, or ambiguous instructions make agents behave unpredictably.
+`dogent` enforces a clear, command-style discipline
+  so every line earns its place.
+
+We respect [agent-sh/agnix](https://github.com/agent-sh/agnix)
+  as a prototype of this idea.
+`dogent` goes further: it is stricter, more opinionated,
+  and aims for extreme quality with no compromise.
+
+## Usage
+
+Run it on any manifesto file, no installation required:
+
+```bash
+npx @yegor256/dogent CLAUDE.md
+```
+
+Lint several files at once:
+
+```bash
+npx @yegor256/dogent SKILL.md CLAUDE.md AGENTS.md
+```
+
+Sample output:
+
+```text
+CLAUDE.md
+  12:  line exceeds 80 symbols
+  18:  not an instruction, sounds like description
+  24:  article "the" detected, remove noise
+  31:  section name too long, use 1-3 words
+
+4 problems found, exit code 1
+```
+
+The command exits with a non-zero status when problems are found,
+  so it plugs directly into CI and pre-commit hooks.
+
+## Rules
+
+`dogent` checks that every manifesto obeys these rules:
+
+- Every line must be an instruction.
+- Instructions must be grouped in sections.
+- Section names must be short, 1-3 words.
+- Every line must be no longer than 80 symbols.
+- Every line must sound like a command.
+- No articles, no noise, no bloated text.
+- Simple grammar, no ambiguity.
+
+## AI verification
+
+`dogent` works standalone by default,
+  using fast deterministic checks with no network access.
+When `OPENAI_API_KEY` or `CLAUDE_TOKEN` is present in the environment,
+  it additionally uses AI to verify the text for ambiguity,
+  weak phrasing, and instructions that only pretend to be commands:
+
+```bash
+export CLAUDE_TOKEN=...
+npx @yegor256/dogent CLAUDE.md
+```
+
+## GitHub Actions
+
+Because `dogent` runs through `npx`, no extra action is needed.
+Add a single step to any workflow to lint your manifestos on every push:
+
+```yaml
+name: dogent
+on: [push, pull_request]
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npx @yegor256/dogent CLAUDE.md SKILL.md
+```
+
+The job fails when `dogent` finds problems,
+  blocking the merge until the manifestos are clean.
+To enable AI verification in CI, expose a token as a secret:
+
+```yaml
+      - run: npx @yegor256/dogent CLAUDE.md
+        env:
+          CLAUDE_TOKEN: ${{ secrets.CLAUDE_TOKEN }}
+```
+
+## Pre-commit hook
+
+Run `dogent` before every commit so broken manifestos never reach history.
+Drop this into `.git/hooks/pre-commit` and make it executable:
+
+```bash
+#!/bin/sh
+npx @yegor256/dogent CLAUDE.md SKILL.md AGENTS.md
+```
+
+Prefer the [pre-commit](https://pre-commit.com) framework?
+Add `dogent` as a local hook in `.pre-commit-config.yaml`:
+
+```yaml
+repos:
+  - repo: local
+    hooks:
+      - id: dogent
+        name: dogent
+        entry: npx @yegor256/dogent
+        language: system
+        files: '(CLAUDE|SKILL|AGENTS)\.md$'
+```
+
+Either way, the commit is rejected until every flagged line is fixed.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "author": "Yegor Bugayenko <yegor256@gmail.com> (https://www.yegor256.com/)",
+  "bin": {
+    "dogent": "./src/dogent.js"
+  },
+  "bugs": "https://github.com/yegor256/dogent/issues",
+  "description": "A strict, opinionated linter for agentic manifesto files (SKILL.md, CLAUDE.md, AGENTS.md)",
+  "devDependencies": {
+    "@eslint/js": "^9.28.0",
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "eslint": "^9.28.0",
+    "globals": "^17.6.0",
+    "mocha": "^11.5.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "src"
+  ],
+  "homepage": "https://github.com/yegor256/dogent",
+  "keywords": [
+    "linter",
+    "lint",
+    "markdown",
+    "claude",
+    "agents",
+    "skill",
+    "manifesto",
+    "cli"
+  ],
+  "license": "MIT",
+  "main": "src/dogent.js",
+  "name": "@yegor256/dogent",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": "yegor256/dogent",
+  "scripts": {
+    "lint": "eslint .",
+    "test": "mocha 'test/**/*.js' --timeout 60000"
+  },
+  "version": "0.0.1"
+}

package/src/document.js

@@ -0,0 +1,30 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Document.
+ *
+ * An entire manifesto already parsed into an ordered collection of
+ * fragments, ready to be walked by a rule that hunts for violations.
+ */
+class Document {
+  constructor(uri, fragments) {
+    this.address = uri;
+    this.pieces = fragments;
+  }
+  uri() {
+    return this.address;
+  }
+  fragments() {
+    return this.pieces;
+  }
+  walk(visitor) {
+    return this.pieces.reduce((all, piece) => all.concat(piece.accept(visitor)), []);
+  }
+}
+
+module.exports = Document;

package/src/dogent.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const fs = require('fs');
+const Markdown = require('./markdown');
+const Report = require('./report');
+const rules = require('./rules');
+
+const argv = process.argv.slice(2);
+const sarif = argv.indexOf('--sarif') !== -1;
+const files = argv.filter((arg) => arg !== '--sarif');
+if (files.length === 0) {
+  process.stderr.write('Usage: dogent [--sarif] <file.md>...\n');
+  process.exit(2);
+}
+const found = [];
+files.forEach((file) => {
+  const document = new Markdown(file, fs.readFileSync(file, 'utf8')).document();
+  rules().forEach((rule) => {
+    rule.violations(document).forEach((violation) => found.push(violation));
+  });
+});
+const report = new Report('dogent', found);
+process.stdout.write(`${sarif ? JSON.stringify(report.sarif(), null, 2) : report.text()}\n`);
+process.exit(report.count() > 0 ? 1 : 0);

package/src/fragments/bullets.js

@@ -0,0 +1,27 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Bullets.
+ *
+ * A composite fragment holding the inner pieces of one bullet list,
+ * dispatching itself first and then every item it contains.
+ */
+class Bullets {
+  constructor(items, line) {
+    this.items = items;
+    this.row = line;
+  }
+  accept(visitor) {
+    return this.items.reduce(
+      (all, item) => all.concat(item.accept(visitor)),
+      [].concat(visitor.bullets(this.row))
+    );
+  }
+}
+
+module.exports = Bullets;

package/src/fragments/header.js

@@ -0,0 +1,25 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Header.
+ *
+ * A section heading line of a manifesto, carrying its raw text,
+ * its line number, and its depth (the count of leading hashes).
+ */
+class Header {
+  constructor(content, line, level) {
+    this.content = content;
+    this.row = line;
+    this.depth = level;
+  }
+  accept(visitor) {
+    return visitor.header(this.content, this.row, this.depth);
+  }
+}
+
+module.exports = Header;

package/src/fragments/prose.js

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Prose.
+ *
+ * A single line of English prose, one instruction of a manifesto,
+ * carrying its raw text and its line number.
+ */
+class Prose {
+  constructor(content, line) {
+    this.content = content;
+    this.row = line;
+  }
+  accept(visitor) {
+    return visitor.prose(this.content, this.row);
+  }
+}
+
+module.exports = Prose;

package/src/fragments/snippet.js

@@ -0,0 +1,24 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Snippet.
+ *
+ * A fenced code block taken as bulk, carrying the whole block as raw
+ * text and the line number where the fence opens.
+ */
+class Snippet {
+  constructor(content, line) {
+    this.content = content;
+    this.row = line;
+  }
+  accept(visitor) {
+    return visitor.snippet(this.content, this.row);
+  }
+}
+
+module.exports = Snippet;

package/src/markdown.js

@@ -0,0 +1,89 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Document = require('./document');
+const Header = require('./fragments/header');
+const Prose = require('./fragments/prose');
+const Bullets = require('./fragments/bullets');
+const Snippet = require('./fragments/snippet');
+
+/**
+ * Markdown.
+ *
+ * The raw text of a manifesto file. Reads itself line by line, holding
+ * the context of the moment (inside a fence, inside a list), and emits
+ * a Document of fragments. This is a line scanner, not a grammar.
+ *
+ * @todo #1:45min Attach wrapped continuation lines to the bullet they
+ *  belong to, instead of silently dropping their nested indentation
+ *  context on the floor.
+ */
+class Markdown {
+  constructor(uri, content) {
+    this.address = uri;
+    this.content = content;
+  }
+  document() {
+    const pieces = [];
+    let fence = '';
+    let block = [];
+    let opened = 0;
+    let items = [];
+    let started = 0;
+    const flush = () => {
+      if (items.length > 0) {
+        pieces.push(new Bullets(items, started));
+        items = [];
+      }
+    };
+    this.content.split('\n').forEach((line, index) => {
+      const row = index + 1;
+      const mark = line.match(/^\s*(?<fence>```|~~~)/u);
+      if (fence !== '') {
+        block.push(line);
+        if (mark && line.trim().indexOf(fence) === 0) {
+          pieces.push(new Snippet(block.join('\n'), opened));
+          fence = '';
+          block = [];
+        }
+        return;
+      }
+      if (mark) {
+        flush();
+        ({fence} = mark.groups);
+        block = [line];
+        opened = row;
+        return;
+      }
+      if (/^#{1,6}\s+/u.test(line)) {
+        flush();
+        pieces.push(new Header(line, row, line.match(/^#+/u)[0].length));
+        return;
+      }
+      if (/^\s*(?:[-*+]|\d+\.)\s+/u.test(line)) {
+        if (items.length === 0) {
+          started = row;
+        }
+        items.push(new Prose(line, row));
+        return;
+      }
+      if (/^\s*$/u.test(line)) {
+        flush();
+        return;
+      }
+      flush();
+      pieces.push(new Prose(line, row));
+    });
+    flush();
+    if (fence !== '') {
+      pieces.push(new Snippet(block.join('\n'), opened));
+    }
+    return new Document(this.address, pieces);
+  }
+}
+
+module.exports = Markdown;

package/src/region.js

@@ -0,0 +1,38 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Region.
+ *
+ * The exact place of a violation inside a file: the file itself, a
+ * one-based line, and a one-based column. Knows how to project itself
+ * into a SARIF physical location.
+ */
+class Region {
+  constructor(uri, line, column) {
+    this.address = uri;
+    this.row = line;
+    this.col = column;
+  }
+  uri() {
+    return this.address;
+  }
+  line() {
+    return this.row;
+  }
+  column() {
+    return this.col;
+  }
+  sarif() {
+    return {
+      artifactLocation: {uri: this.address},
+      region: {startLine: this.row, startColumn: this.col}
+    };
+  }
+}
+
+module.exports = Region;

package/src/report.js

@@ -0,0 +1,40 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Report.
+ *
+ * The whole verdict of a run: the tool that produced it and every
+ * violation it gathered. Renders itself for humans or as a SARIF log.
+ */
+class Report {
+  constructor(tool, violations) {
+    this.tool = tool;
+    this.bag = violations;
+  }
+  count() {
+    return this.bag.length;
+  }
+  text() {
+    return this.bag
+      .map((violation) => violation.text())
+      .concat(`${this.bag.length} problems found`)
+      .join('\n');
+  }
+  sarif() {
+    return {
+      version: '2.1.0',
+      $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+      runs: [{
+        tool: {driver: {name: this.tool, rules: []}},
+        results: this.bag.map((violation) => violation.sarif())
+      }]
+    };
+  }
+}
+
+module.exports = Report;

package/src/rules/command.js

@@ -0,0 +1,56 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Command.
+ *
+ * Demands that every instruction sound like a command. A standalone
+ * checker can only guess: it flags lines that open with a pronoun or
+ * end with a question mark, both signs of description, not order.
+ *
+ * @todo #1:90min Replace this heuristic with a real imperative-mood check
+ *  driven by an AI oracle when a token is present in the environment.
+ */
+class Command {
+  constructor() {
+    this.id = 'command';
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.judge(text, line, uri),
+      snippet: () => [],
+      bullets: () => []
+    });
+  }
+  judge(text, line, uri) {
+    const clean = text.replace(/^\s*(?:[-*+]|\d+\.)\s+/u, '').trim();
+    if (clean === '') {
+      return [];
+    }
+    const first = clean
+      .split(/\s+/u)[0]
+      .toLowerCase()
+      .replace(/[^a-z]/gu, '');
+    const weak = /^(?:i|you|we|they|he|she|it|this|that|these|those|there|here)$/u;
+    if (!weak.test(first) && clean.slice(-1) !== '?') {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'warning',
+      'line must sound like a command',
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = Command;

package/src/rules/grouped.js

@@ -0,0 +1,46 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * Grouped.
+ *
+ * Demands that every instruction live under a section. Any prose that
+ * appears before the first heading is loose and therefore a violation.
+ */
+class Grouped {
+  constructor() {
+    this.id = 'grouped';
+  }
+  violations(document) {
+    const uri = document.uri();
+    const marks = document.walk({
+      header: (text, line) => [{header: true, line}],
+      prose: (text, line) => [{header: false, line}],
+      snippet: () => [],
+      bullets: () => []
+    });
+    let first = Infinity;
+    marks.forEach((mark) => {
+      if (mark.header && mark.line < first) {
+        first = mark.line;
+      }
+    });
+    return marks
+      .filter((mark) => !mark.header && mark.line < first)
+      .map((mark) => new Violation(
+        this.id,
+        'error',
+        'instruction not grouped under a section',
+        new Region(uri, mark.line, 1)
+      ));
+  }
+}
+
+module.exports = Grouped;

package/src/rules/index.js

@@ -0,0 +1,20 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const LineLength = require('./line-length');
+const ShortSections = require('./short-sections');
+const Grouped = require('./grouped');
+const NoArticles = require('./no-articles');
+const Command = require('./command');
+
+module.exports = () => [
+  new Grouped(),
+  new ShortSections(),
+  new LineLength(80),
+  new NoArticles(),
+  new Command()
+];

package/src/rules/line-length.js

@@ -0,0 +1,44 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * LineLength.
+ *
+ * Demands that every instruction and every heading stay within a
+ * maximum width. Code snippets are exempt, since code is not prose.
+ */
+class LineLength {
+  constructor(max) {
+    this.id = 'line-length';
+    this.max = max;
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: (text, line) => this.over(text, line, uri),
+      prose: (text, line) => this.over(text, line, uri),
+      snippet: () => [],
+      bullets: () => []
+    });
+  }
+  over(text, line, uri) {
+    if (text.length <= this.max) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'error',
+      `line exceeds ${this.max} symbols, has ${text.length}`,
+      new Region(uri, line, this.max + 1)
+    )];
+  }
+}
+
+module.exports = LineLength;

package/src/rules/no-articles.js

@@ -0,0 +1,47 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * NoArticles.
+ *
+ * Demands that instructions carry no articles, the cheapest kind of
+ * noise. Flags every standalone "a", "an", and "the".
+ */
+class NoArticles {
+  constructor() {
+    this.id = 'no-articles';
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: () => [],
+      prose: (text, line) => this.scan(text, line, uri),
+      snippet: () => [],
+      bullets: () => []
+    });
+  }
+  scan(text, line, uri) {
+    const found = [];
+    const regex = /\b(?:a|an|the)\b/giu;
+    let hit = regex.exec(text);
+    while (hit !== null) {
+      found.push(new Violation(
+        this.id,
+        'error',
+        `article "${hit[0]}" must be removed`,
+        new Region(uri, line, hit.index + 1)
+      ));
+      hit = regex.exec(text);
+    }
+    return found;
+  }
+}
+
+module.exports = NoArticles;

package/src/rules/short-sections.js

@@ -0,0 +1,48 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+const Violation = require('../violation');
+const Region = require('../region');
+
+/**
+ * ShortSections.
+ *
+ * Demands that every section name be a short label of one to three
+ * words, so the manifesto reads as a map and not as prose.
+ */
+class ShortSections {
+  constructor() {
+    this.id = 'short-sections';
+  }
+  violations(document) {
+    const uri = document.uri();
+    return document.walk({
+      header: (text, line) => this.named(text, line, uri),
+      prose: () => [],
+      snippet: () => [],
+      bullets: () => []
+    });
+  }
+  named(text, line, uri) {
+    const words = text
+      .replace(/^#{1,6}\s+/u, '')
+      .trim()
+      .split(/\s+/u)
+      .filter((word) => word !== '');
+    if (words.length >= 1 && words.length <= 3) {
+      return [];
+    }
+    return [new Violation(
+      this.id,
+      'error',
+      `section name must be 1-3 words, has ${words.length}`,
+      new Region(uri, line, 1)
+    )];
+  }
+}
+
+module.exports = ShortSections;

package/src/violation.js

@@ -0,0 +1,39 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 Yegor Bugayenko
+ * SPDX-License-Identifier: MIT
+ */
+
+'use strict';
+
+/**
+ * Violation.
+ *
+ * One breach of one rule at one region of a manifesto. Renders itself
+ * either as a terse human line or as a SARIF result.
+ */
+class Violation {
+  constructor(rule, level, message, region) {
+    this.rule = rule;
+    this.level = level;
+    this.message = message;
+    this.spot = region;
+  }
+  text() {
+    return [
+      `${this.spot.uri()}:${this.spot.line()}:${this.spot.column()}`,
+      this.level,
+      this.rule,
+      this.message
+    ].join(' ');
+  }
+  sarif() {
+    return {
+      ruleId: this.rule,
+      level: this.level,
+      message: {text: this.message},
+      locations: [{physicalLocation: this.spot.sarif()}]
+    };
+  }
+}
+
+module.exports = Violation;