agent-rules-lint 0.1.1__tar.gz

agent_rules_lint-0.1.1/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

agent_rules_lint-0.1.1/.github/ISSUE_TEMPLATE/rule_request.yml

@@ -0,0 +1,27 @@
+name: Rule request
+description: Suggest a new lint rule
+title: "[Rule] "
+labels:
+  - rule-request
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What agent instruction problem should this catch?
+    validations:
+      required: true
+  - type: textarea
+    id: example
+    attributes:
+      label: Example
+      description: Provide a short instruction snippet that should trigger the rule.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected finding
+      description: What should the tool report?
+    validations:
+      required: true

agent_rules_lint-0.1.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,11 @@
+## Summary
+
+- 
+
+## Checks
+
+- [ ] `python -m unittest discover -s tests`
+- [ ] `python -m agent_rules_lint .`
+
+## Notes
+

agent_rules_lint-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.10", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v7.0.0
+      - uses: actions/setup-python@v6.3.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install package
+        run: python -m pip install -e .
+      - name: Run tests
+        run: python -m unittest discover -s tests -v
+      - name: Compile source
+        run: python -m compileall -q agent_rules_lint tests
+      - name: Run linter on itself
+        run: python -m agent_rules_lint .
+
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.0
+      - uses: actions/setup-python@v6.3.0
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - run: python -m pip install dist/*.whl
+      - run: agent-rules-lint --version

agent_rules_lint-0.1.1/.github/workflows/release.yml

@@ -0,0 +1,40 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.0
+      - uses: actions/setup-python@v6.3.0
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v7.0.1
+        with:
+          name: python-package
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agent-rules-lint
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8.0.0
+        with:
+          name: python-package
+          path: dist/
+      - name: Publish distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

agent_rules_lint-0.1.1/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.venv/
+venv/
+dist/
+build/
+*.egg-info/
+*.pyc
+.DS_Store
+Thumbs.db

agent_rules_lint-0.1.1/AGENTS.md

@@ -0,0 +1,31 @@
+# Agent Instructions
+
+## Purpose
+
+Maintain `agent-rules-lint`, a dependency-free Python CLI for linting AI agent instruction files.
+
+## Scope
+
+These instructions apply to code, tests, documentation, and GitHub workflow files in this repository.
+
+## Commands
+
+Run the standard checks before publishing:
+
+```bash
+python -m unittest discover -s tests
+python -m agent_rules_lint .
+```
+
+## Safety
+
+- Do not add network calls to the default lint path.
+- Do not add model calls to the default lint path.
+- Do not commit API keys, access tokens, cookies, private credentials, or generated build output.
+- Keep checks deterministic so they are safe for CI.
+
+## Style
+
+- Prefer standard-library Python.
+- Keep rule messages short and actionable.
+- Add tests when changing lint behavior.

agent_rules_lint-0.1.1/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to `agent-rules-lint` are documented here.
+
+## [0.1.1] - 2026-07-14
+
+### Added
+
+- PyPI installation instructions for `uvx`, `pipx`, and `pip`.
+- Credential-free PyPI publishing with GitHub Trusted Publishing.
+- Cross-platform CI for Python 3.10 and 3.14.
+- Package build, metadata, wheel installation, and CLI smoke checks.
+
+### Fixed
+
+- Project metadata links now point to the current `Uky0Yang` repository.
+
+## [0.1.0] - 2026-07-01
+
+- Initial public release.
+
+[0.1.1]: https://github.com/Uky0Yang/agent-rules-lint/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/Uky0Yang/agent-rules-lint/releases/tag/v0.1.0

agent_rules_lint-0.1.1/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing
+
+Thanks for helping improve `agent-rules-lint`.
+
+## Good Contributions
+
+- New checks for common agent instruction mistakes
+- Better false-positive handling
+- Tests for real-world `AGENTS.md`, `CLAUDE.md`, Cursor, or Copilot instruction patterns
+- Documentation examples
+- CI integration examples
+
+## Before Opening a PR
+
+Run:
+
+```bash
+python -m unittest discover -s tests -v
+python -m compileall -q agent_rules_lint tests
+python -m agent_rules_lint .
+```
+
+If your change adds or changes a lint rule, include tests.
+
+## Rule Design
+
+Rules should be:
+
+- Easy to explain
+- Low noise
+- Useful without sending data to a model
+- Safe for public and private repositories
+
+Avoid checks that require personal taste or project-specific assumptions.

agent_rules_lint-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ukyo
+
+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.

agent_rules_lint-0.1.1/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: agent-rules-lint
+Version: 0.1.1
+Summary: Lint AI agent instruction files such as AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions.
+Project-URL: Homepage, https://github.com/Uky0Yang/agent-rules-lint
+Project-URL: Repository, https://github.com/Uky0Yang/agent-rules-lint
+Project-URL: Issues, https://github.com/Uky0Yang/agent-rules-lint/issues
+Project-URL: Changelog, https://github.com/Uky0Yang/agent-rules-lint/blob/main/CHANGELOG.md
+Author: Ukyo
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agents,claude-code,copilot,cursor,developer-tools,lint,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# agent-rules-lint
+
+[![PyPI](https://img.shields.io/pypi/v/agent-rules-lint)](https://pypi.org/project/agent-rules-lint/)
+[![Python](https://img.shields.io/pypi/pyversions/agent-rules-lint)](https://pypi.org/project/agent-rules-lint/)
+[![CI](https://github.com/Uky0Yang/agent-rules-lint/actions/workflows/ci.yml/badge.svg)](https://github.com/Uky0Yang/agent-rules-lint/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Lint AI agent instruction files before they confuse your coding agent.
+
+`agent-rules-lint` is a small, dependency-free Python CLI that scans files such as `AGENTS.md`, `CLAUDE.md`, Cursor rules, and GitHub Copilot instructions for common quality and safety problems.
+
+## Why
+
+Recent high-growth developer repos show a clear pattern: teams are adding more agent skills, rule files, memory files, and coding-agent playbooks. The missing piece is a quick quality gate for those instructions.
+
+Bad agent instructions are expensive. They can be too long, vague, contradictory, unsafe, or accidentally include secrets. This tool gives you a fast local and CI check before those rules affect real work.
+
+## What It Checks
+
+- Common instruction files:
+  - `AGENTS.md`
+  - `CLAUDE.md`
+  - `GEMINI.md`
+  - `.cursorrules`
+  - `.cursor/rules/*.md`
+  - `.github/copilot-instructions.md`
+  - `.github/instructions/*.md`
+- Secret-like values
+- Risky shell and Git commands
+- Prompt-injection-like language
+- Missing title
+- Missing purpose, scope, command, or safety guidance
+- Vague language
+- Files that are too long for practical agent use
+- A small set of obvious contradictory rules
+
+## Install
+
+Run it without installing:
+
+```bash
+uvx agent-rules-lint .
+```
+
+Or install it as an isolated CLI:
+
+```bash
+pipx install agent-rules-lint
+agent-rules-lint .
+```
+
+Standard pip installation also works:
+
+```bash
+python -m pip install agent-rules-lint
+```
+
+For local development:
+
+```bash
+python -m pip install -e .
+```
+
+## Usage
+
+Scan the current repository:
+
+```bash
+agent-rules-lint .
+```
+
+Return JSON for CI or custom reports:
+
+```bash
+agent-rules-lint . --format json
+```
+
+Fail CI on warnings:
+
+```bash
+agent-rules-lint . --warnings-as-errors
+```
+
+Change the long-file threshold:
+
+```bash
+agent-rules-lint . --max-chars 8000
+```
+
+## Example Output
+
+```text
+agent-rules-lint checked 1 file(s)
+errors=0 warnings=1 info=2
+
+Files:
+  - AGENTS.md
+
+Findings:
+  [warning] AGENTS.md:42 risky-command: Risky command should include explicit safeguards or approval rules.
+  [info] AGENTS.md missing-safety: Consider adding a clear safety section.
+```
+
+## CI
+
+Add this to GitHub Actions:
+
+```yaml
+name: Lint agent rules
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  lint-agent-rules:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.0
+      - uses: actions/setup-python@v6.3.0
+        with:
+          python-version: "3.12"
+      - run: pipx run agent-rules-lint . --warnings-as-errors
+```
+
+## Design Principles
+
+- No model calls
+- No network calls
+- No dependencies
+- Safe to run in CI
+- Findings should be specific enough to act on
+- Warnings should improve instruction quality, not enforce one writing style
+
+## Current Limitations
+
+- Conflict detection is intentionally conservative and only catches obvious pairs.
+- It does not estimate real tokenizer counts; it uses character length as a practical proxy.
+- It does not validate whether an instruction is correct for a specific tool.
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m agent_rules_lint .
+```
+
+## Agent OSS Toolkit
+
+This project is part of a small toolkit for building and launching agent-ready open-source repositories:
+
+- [agent-repo-kit](https://github.com/Uky0Yang/agent-repo-kit): scaffold launch-ready, AI-agent-friendly repositories
+- [oss-launch-check](https://github.com/Uky0Yang/oss-launch-check): audit whether a repository is ready to launch as open source
+- [repo-context-card](https://github.com/Uky0Yang/repo-context-card): generate compact repository context cards for coding agents
+- [agent-rules-lint](https://github.com/Uky0Yang/agent-rules-lint): lint AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions
+- [awesome-ai-agents-zh](https://github.com/Uky0Yang/awesome-ai-agents-zh): Chinese AI Agents / MCP / AI DevTools directory
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

agent_rules_lint-0.1.1/README.md

@@ -0,0 +1,167 @@
+# agent-rules-lint
+
+[![PyPI](https://img.shields.io/pypi/v/agent-rules-lint)](https://pypi.org/project/agent-rules-lint/)
+[![Python](https://img.shields.io/pypi/pyversions/agent-rules-lint)](https://pypi.org/project/agent-rules-lint/)
+[![CI](https://github.com/Uky0Yang/agent-rules-lint/actions/workflows/ci.yml/badge.svg)](https://github.com/Uky0Yang/agent-rules-lint/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Lint AI agent instruction files before they confuse your coding agent.
+
+`agent-rules-lint` is a small, dependency-free Python CLI that scans files such as `AGENTS.md`, `CLAUDE.md`, Cursor rules, and GitHub Copilot instructions for common quality and safety problems.
+
+## Why
+
+Recent high-growth developer repos show a clear pattern: teams are adding more agent skills, rule files, memory files, and coding-agent playbooks. The missing piece is a quick quality gate for those instructions.
+
+Bad agent instructions are expensive. They can be too long, vague, contradictory, unsafe, or accidentally include secrets. This tool gives you a fast local and CI check before those rules affect real work.
+
+## What It Checks
+
+- Common instruction files:
+  - `AGENTS.md`
+  - `CLAUDE.md`
+  - `GEMINI.md`
+  - `.cursorrules`
+  - `.cursor/rules/*.md`
+  - `.github/copilot-instructions.md`
+  - `.github/instructions/*.md`
+- Secret-like values
+- Risky shell and Git commands
+- Prompt-injection-like language
+- Missing title
+- Missing purpose, scope, command, or safety guidance
+- Vague language
+- Files that are too long for practical agent use
+- A small set of obvious contradictory rules
+
+## Install
+
+Run it without installing:
+
+```bash
+uvx agent-rules-lint .
+```
+
+Or install it as an isolated CLI:
+
+```bash
+pipx install agent-rules-lint
+agent-rules-lint .
+```
+
+Standard pip installation also works:
+
+```bash
+python -m pip install agent-rules-lint
+```
+
+For local development:
+
+```bash
+python -m pip install -e .
+```
+
+## Usage
+
+Scan the current repository:
+
+```bash
+agent-rules-lint .
+```
+
+Return JSON for CI or custom reports:
+
+```bash
+agent-rules-lint . --format json
+```
+
+Fail CI on warnings:
+
+```bash
+agent-rules-lint . --warnings-as-errors
+```
+
+Change the long-file threshold:
+
+```bash
+agent-rules-lint . --max-chars 8000
+```
+
+## Example Output
+
+```text
+agent-rules-lint checked 1 file(s)
+errors=0 warnings=1 info=2
+
+Files:
+  - AGENTS.md
+
+Findings:
+  [warning] AGENTS.md:42 risky-command: Risky command should include explicit safeguards or approval rules.
+  [info] AGENTS.md missing-safety: Consider adding a clear safety section.
+```
+
+## CI
+
+Add this to GitHub Actions:
+
+```yaml
+name: Lint agent rules
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  lint-agent-rules:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.0
+      - uses: actions/setup-python@v6.3.0
+        with:
+          python-version: "3.12"
+      - run: pipx run agent-rules-lint . --warnings-as-errors
+```
+
+## Design Principles
+
+- No model calls
+- No network calls
+- No dependencies
+- Safe to run in CI
+- Findings should be specific enough to act on
+- Warnings should improve instruction quality, not enforce one writing style
+
+## Current Limitations
+
+- Conflict detection is intentionally conservative and only catches obvious pairs.
+- It does not estimate real tokenizer counts; it uses character length as a practical proxy.
+- It does not validate whether an instruction is correct for a specific tool.
+
+## Development
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests -v
+python -m agent_rules_lint .
+```
+
+## Agent OSS Toolkit
+
+This project is part of a small toolkit for building and launching agent-ready open-source repositories:
+
+- [agent-repo-kit](https://github.com/Uky0Yang/agent-repo-kit): scaffold launch-ready, AI-agent-friendly repositories
+- [oss-launch-check](https://github.com/Uky0Yang/oss-launch-check): audit whether a repository is ready to launch as open source
+- [repo-context-card](https://github.com/Uky0Yang/repo-context-card): generate compact repository context cards for coding agents
+- [agent-rules-lint](https://github.com/Uky0Yang/agent-rules-lint): lint AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions
+- [awesome-ai-agents-zh](https://github.com/Uky0Yang/awesome-ai-agents-zh): Chinese AI Agents / MCP / AI DevTools directory
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT

agent_rules_lint-0.1.1/ROADMAP.md

@@ -0,0 +1,29 @@
+# Roadmap
+
+## Near Term
+
+- Add more real-world examples
+- Add markdown output
+- Add line excerpts in JSON output
+- Support config in `pyproject.toml`
+- Keep PyPI releases automated through Trusted Publishing
+
+## Mid Term
+
+- Add rule IDs with documentation pages
+- Add SARIF output for GitHub code scanning
+- Add pre-commit hook documentation
+- Add optional token estimation adapters
+- Add fixture corpus from public agent instruction files
+
+## Long Term
+
+- Build a benchmark of high-quality agent instruction files
+- Add project-specific profiles for Codex, Claude Code, Cursor, Copilot, and Gemini CLI
+- Provide a GitHub Action wrapper
+
+## Non-Goals
+
+- No model-based scoring by default
+- No network calls by default
+- No automatic rewriting of user instructions without explicit user action

agent_rules_lint-0.1.1/agent_rules_lint/__init__.py

@@ -0,0 +1,3 @@
+"""Lint AI agent instruction files."""
+
+__version__ = "0.1.1"

agent_rules_lint-0.1.1/agent_rules_lint/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent_rules_lint-0.1.1/agent_rules_lint/cli.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+import sys
+
+from . import __version__
+from .linter import LintResult, lint_path
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="agent-rules-lint",
+        description="Lint AI agent instruction files such as AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions.",
+    )
+    parser.add_argument("path", nargs="?", default=".", help="Repository or directory to scan.")
+    parser.add_argument("--format", choices=("text", "json"), default="text", help="Output format.")
+    parser.add_argument("--max-chars", type=int, default=12000, help="Warn when a file exceeds this many characters.")
+    parser.add_argument("--warnings-as-errors", action="store_true", help="Exit non-zero when warnings are found.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def render_text(result: LintResult) -> str:
+    lines = [
+        f"agent-rules-lint checked {len(result.files_checked)} file(s)",
+        f"errors={result.error_count} warnings={result.warning_count} info={result.info_count}",
+    ]
+    if result.files_checked:
+        lines.append("")
+        lines.append("Files:")
+        for file in result.files_checked:
+            lines.append(f"  - {file}")
+
+    if result.findings:
+        lines.append("")
+        lines.append("Findings:")
+        for finding in result.findings:
+            location = finding.file
+            if finding.line is not None:
+                location = f"{location}:{finding.line}"
+            lines.append(f"  [{finding.severity}] {location} {finding.rule}: {finding.message}")
+    else:
+        lines.append("")
+        lines.append("No findings.")
+
+    return "\n".join(lines)
+
+
+def exit_code(result: LintResult, warnings_as_errors: bool) -> int:
+    if result.error_count:
+        return 1
+    if warnings_as_errors and result.warning_count:
+        return 1
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    result = lint_path(Path(args.path), max_chars=args.max_chars)
+
+    if args.format == "json":
+        print(result.to_json())
+    else:
+        print(render_text(result))
+
+    return exit_code(result, warnings_as_errors=args.warnings_as_errors)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

agent_rules_lint-0.1.1/agent_rules_lint/linter.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+import fnmatch
+import json
+import re
+from typing import Iterable
+
+
+DEFAULT_PATTERNS = (
+    "AGENTS.md",
+    "CLAUDE.md",
+    "GEMINI.md",
+    ".cursorrules",
+    ".cursor/rules/*.md",
+    ".github/copilot-instructions.md",
+    ".github/instructions/*.md",
+)
+
+DEFAULT_IGNORE_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".venv",
+    "venv",
+    "node_modules",
+    "__pycache__",
+    "dist",
+    "build",
+}
+
+SECRET_PATTERNS = (
+    re.compile(r"\bghp_[A-Za-z0-9_]{20,}\b"),
+    re.compile(r"\bgho_[A-Za-z0-9_]{20,}\b"),
+    re.compile(r"\bgithub_pat_[A-Za-z0-9_]{20,}\b"),
+    re.compile(r"\bsk-[A-Za-z0-9_-]{20,}\b"),
+    re.compile(r"\bAKIA[0-9A-Z]{16}\b"),
+    re.compile(r"-----BEGIN (RSA |OPENSSH |EC |DSA )?PRIVATE KEY-----"),
+)
+
+RISKY_COMMAND_PATTERNS = (
+    re.compile(r"\brm\s+-rf\s+[/~$*]", re.IGNORECASE),
+    re.compile(r"\bgit\s+reset\s+--hard\b", re.IGNORECASE),
+    re.compile(r"\bgit\s+clean\s+-fdx\b", re.IGNORECASE),
+    re.compile(r"\bRemove-Item\b.+\b-Recurse\b.+\b-Force\b", re.IGNORECASE),
+    re.compile(r"\bcurl\b.+\|\s*(bash|sh)\b", re.IGNORECASE),
+    re.compile(r"\bwget\b.+\|\s*(bash|sh)\b", re.IGNORECASE),
+)
+
+PROMPT_INJECTION_PATTERNS = (
+    re.compile(r"ignore (all )?(previous|prior|above) instructions", re.IGNORECASE),
+    re.compile(r"reveal (the )?(system|developer) (prompt|message)", re.IGNORECASE),
+    re.compile(r"bypass (safety|policy|guardrails)", re.IGNORECASE),
+)
+
+SECTION_HINTS = {
+    "purpose": ("purpose", "goal", "objective", "what this does", "overview", "目标", "目的"),
+    "scope": ("scope", "when to use", "applies to", "boundaries", "范围", "适用"),
+    "commands": ("commands", "scripts", "verification", "tests", "test", "build", "命令", "验证", "测试"),
+    "safety": ("safety", "security", "secrets", "do not", "never", "安全", "密钥", "不要"),
+    "style": ("style", "formatting", "conventions", "tone", "风格", "格式", "约定"),
+}
+
+
+@dataclass(frozen=True)
+class Finding:
+    file: str
+    severity: str
+    rule: str
+    message: str
+    line: int | None = None
+
+    def to_dict(self) -> dict:
+        data = {
+            "file": self.file,
+            "severity": self.severity,
+            "rule": self.rule,
+            "message": self.message,
+        }
+        if self.line is not None:
+            data["line"] = self.line
+        return data
+
+
+@dataclass
+class LintResult:
+    root: str
+    files_checked: list[str] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+
+    @property
+    def error_count(self) -> int:
+        return sum(1 for finding in self.findings if finding.severity == "error")
+
+    @property
+    def warning_count(self) -> int:
+        return sum(1 for finding in self.findings if finding.severity == "warning")
+
+    @property
+    def info_count(self) -> int:
+        return sum(1 for finding in self.findings if finding.severity == "info")
+
+    def to_dict(self) -> dict:
+        return {
+            "root": self.root,
+            "files_checked": self.files_checked,
+            "summary": {
+                "errors": self.error_count,
+                "warnings": self.warning_count,
+                "info": self.info_count,
+            },
+            "findings": [finding.to_dict() for finding in self.findings],
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=2)
+
+
+def discover_instruction_files(root: Path, patterns: Iterable[str] = DEFAULT_PATTERNS) -> list[Path]:
+    root = root.resolve()
+    matches: list[Path] = []
+    normalized_patterns = tuple(pattern.replace("\\", "/") for pattern in patterns)
+
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        if any(part in DEFAULT_IGNORE_DIRS for part in path.relative_to(root).parts):
+            continue
+        relative = path.relative_to(root).as_posix()
+        if any(fnmatch.fnmatch(relative, pattern) for pattern in normalized_patterns):
+            matches.append(path)
+
+    return sorted(matches, key=lambda item: item.relative_to(root).as_posix())
+
+
+def lint_path(root: Path, max_chars: int = 12000) -> LintResult:
+    root = root.resolve()
+    result = LintResult(root=str(root))
+    files = discover_instruction_files(root)
+
+    if not files:
+        result.findings.append(
+            Finding(
+                file=".",
+                severity="warning",
+                rule="no-instruction-files",
+                message="No known agent instruction files found.",
+            )
+        )
+        return result
+
+    for path in files:
+        relative = path.relative_to(root).as_posix()
+        result.files_checked.append(relative)
+        result.findings.extend(lint_file(path, root, max_chars=max_chars))
+
+    return result
+
+
+def lint_file(path: Path, root: Path, max_chars: int = 12000) -> list[Finding]:
+    relative = path.relative_to(root).as_posix()
+    text = path.read_text(encoding="utf-8", errors="replace")
+    lines = text.splitlines()
+    findings: list[Finding] = []
+
+    if not text.strip():
+        findings.append(Finding(relative, "error", "empty-file", "Instruction file is empty."))
+        return findings
+
+    if len(text) > max_chars:
+        findings.append(
+            Finding(
+                relative,
+                "warning",
+                "too-long",
+                f"Instruction file is {len(text)} characters; consider splitting or tightening it.",
+            )
+        )
+
+    if not re.search(r"^#\s+\S+", text, flags=re.MULTILINE):
+        findings.append(Finding(relative, "warning", "missing-title", "Add a top-level heading."))
+
+    present_sections = detect_sections(text)
+    for section in ("purpose", "scope", "commands", "safety"):
+        if section not in present_sections:
+            findings.append(
+                Finding(
+                    relative,
+                    "info",
+                    f"missing-{section}",
+                    f"Consider adding a clear {section} section.",
+                )
+            )
+
+    findings.extend(scan_patterns(relative, lines, SECRET_PATTERNS, "error", "secret-like-value", "Looks like a secret or private key."))
+    findings.extend(scan_patterns(relative, lines, RISKY_COMMAND_PATTERNS, "warning", "risky-command", "Risky command should include explicit safeguards or approval rules."))
+    findings.extend(scan_patterns(relative, lines, PROMPT_INJECTION_PATTERNS, "warning", "prompt-injection", "Instruction resembles prompt-injection language."))
+    findings.extend(scan_weak_language(relative, lines))
+    findings.extend(scan_absolute_claims(relative, lines))
+    findings.extend(scan_conflicts(relative, lines))
+
+    return findings
+
+
+def detect_sections(text: str) -> set[str]:
+    lowered = text.lower()
+    present: set[str] = set()
+    for section, hints in SECTION_HINTS.items():
+        if any(hint in lowered for hint in hints):
+            present.add(section)
+    return present
+
+
+def scan_patterns(
+    relative: str,
+    lines: list[str],
+    patterns: Iterable[re.Pattern[str]],
+    severity: str,
+    rule: str,
+    message: str,
+) -> list[Finding]:
+    findings: list[Finding] = []
+    for line_number, line in enumerate(lines, start=1):
+        if any(pattern.search(line) for pattern in patterns):
+            findings.append(Finding(relative, severity, rule, message, line_number))
+    return findings
+
+
+def scan_weak_language(relative: str, lines: list[str]) -> list[Finding]:
+    findings: list[Finding] = []
+    pattern = re.compile(r"\b(try to|maybe|if possible|do your best|尽量|可能的话)\b", re.IGNORECASE)
+    for line_number, line in enumerate(lines, start=1):
+        if pattern.search(line):
+            findings.append(
+                Finding(
+                    relative,
+                    "info",
+                    "weak-language",
+                    "Vague language can make agent behavior inconsistent.",
+                    line_number,
+                )
+            )
+    return findings
+
+
+def scan_absolute_claims(relative: str, lines: list[str]) -> list[Finding]:
+    findings: list[Finding] = []
+    pattern = re.compile(r"\b(always|never|must|禁止|必须|永远|绝不)\b", re.IGNORECASE)
+    for line_number, line in enumerate(lines, start=1):
+        if pattern.search(line) and len(line) > 180:
+            findings.append(
+                Finding(
+                    relative,
+                    "info",
+                    "long-absolute-rule",
+                    "Long absolute rules are hard to follow; split into short, testable bullets.",
+                    line_number,
+                )
+            )
+    return findings
+
+
+def scan_conflicts(relative: str, lines: list[str]) -> list[Finding]:
+    text = "\n".join(lines).lower()
+    findings: list[Finding] = []
+    conflict_pairs = (
+        ("always ask", "never ask"),
+        ("always commit", "never commit"),
+        ("always browse", "never browse"),
+        ("must use python", "never use python"),
+        ("必须询问", "不要询问"),
+    )
+    for left, right in conflict_pairs:
+        if left in text and right in text:
+            findings.append(
+                Finding(
+                    relative,
+                    "warning",
+                    "possible-conflict",
+                    f"Possible conflicting instructions: '{left}' and '{right}'.",
+                )
+            )
+    return findings

agent_rules_lint-0.1.1/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "agent-rules-lint"
+version = "0.1.1"
+description = "Lint AI agent instruction files such as AGENTS.md, CLAUDE.md, Cursor rules, and Copilot instructions."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+  { name = "Ukyo" }
+]
+keywords = ["ai-agents", "llm", "developer-tools", "lint", "claude-code", "cursor", "copilot"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Quality Assurance",
+  "Topic :: Utilities"
+]
+dependencies = []
+
+[project.scripts]
+agent-rules-lint = "agent_rules_lint.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/Uky0Yang/agent-rules-lint"
+Repository = "https://github.com/Uky0Yang/agent-rules-lint"
+Issues = "https://github.com/Uky0Yang/agent-rules-lint/issues"
+Changelog = "https://github.com/Uky0Yang/agent-rules-lint/blob/main/CHANGELOG.md"

agent_rules_lint-0.1.1/tests/test_cli.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from contextlib import redirect_stdout
+from io import StringIO
+from pathlib import Path
+
+from agent_rules_lint.cli import main
+
+
+class CliTests(unittest.TestCase):
+    def test_clean_file_exits_zero(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "AGENTS.md").write_text(
+                "# Rules\n\n"
+                "## Purpose\n\nHelp agents.\n\n"
+                "## Scope\n\nThis repo.\n\n"
+                "## Commands\n\nRun tests.\n\n"
+                "## Safety\n\nDo not commit secrets.\n",
+                encoding="utf-8",
+            )
+
+            with redirect_stdout(StringIO()):
+                self.assertEqual(main([str(root)]), 0)
+
+    def test_warnings_as_errors_exits_nonzero(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "AGENTS.md").write_text("# Rules\n\nRun `git reset --hard`.", encoding="utf-8")
+
+            with redirect_stdout(StringIO()):
+                self.assertEqual(main([str(root), "--warnings-as-errors"]), 1)
+
+
+if __name__ == "__main__":
+    unittest.main()

agent_rules_lint-0.1.1/tests/test_linter.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import tempfile
+import unittest
+from pathlib import Path
+
+from agent_rules_lint.linter import discover_instruction_files, lint_path
+
+
+class LinterTests(unittest.TestCase):
+    def test_discovers_common_instruction_files(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "AGENTS.md").write_text("# Agent\n\nPurpose section.", encoding="utf-8")
+            (root / ".cursor" / "rules").mkdir(parents=True)
+            (root / ".cursor" / "rules" / "ui.md").write_text("# UI\n\nScope section.", encoding="utf-8")
+            (root / "README.md").write_text("# Ignore", encoding="utf-8")
+
+            resolved_root = root.resolve()
+            discovered = [path.relative_to(resolved_root).as_posix() for path in discover_instruction_files(root)]
+
+            self.assertEqual(discovered, [".cursor/rules/ui.md", "AGENTS.md"])
+
+    def test_flags_secret_like_values(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "CLAUDE.md").write_text("# Rules\n\nUse token sk-abcdefghijklmnopqrstuvwxyz123456.", encoding="utf-8")
+
+            result = lint_path(root)
+
+            self.assertEqual(result.error_count, 1)
+            self.assertTrue(any(finding.rule == "secret-like-value" for finding in result.findings))
+
+    def test_flags_risky_commands_without_failing_by_default(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            root = Path(directory)
+            (root / "AGENTS.md").write_text("# Rules\n\nRun `git reset --hard` when stuck.", encoding="utf-8")
+
+            result = lint_path(root)
+
+            self.assertEqual(result.error_count, 0)
+            self.assertTrue(any(finding.rule == "risky-command" for finding in result.findings))
+
+    def test_warns_when_no_instruction_files(self) -> None:
+        with tempfile.TemporaryDirectory() as directory:
+            result = lint_path(Path(directory))
+
+            self.assertEqual(result.warning_count, 1)
+            self.assertEqual(result.findings[0].rule, "no-instruction-files")
+
+
+if __name__ == "__main__":
+    unittest.main()