ryni 0.1.0__tar.gz

ryni-0.1.0/.gitignore

@@ -0,0 +1,91 @@
+# Git worktrees
+worktrees/
+
+# SQLite (default local path for api booking store)
+booking.db
+booking.db-wal
+booking.db-shm
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+
+# Node
+node_modules/
+.next/
+.turbo/
+*.tsbuildinfo
+
+# Env files (keep .env.example committed)
+.env
+.env.local
+.env.*.local
+!.env.example
+
+# Office
+*.docx
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/*
+!.vscode/*.code-workspace
+*.swp
+
+# Unused agent tooling
+.gemini/
+
+# Logs
+*.log
+logs/
+
+# Secrets
+*.pem
+*.key
+
+# Sveltekit
+.svelte-kit/
+build/
+out/
+dist/
+
+# Ignore harness logs
+.cursor/hooks/.harness-edit-log.ndjson
+.cursor/hooks/.harness-analysis-log.json
+.cursor/hooks/.harness-analysis-log.ndjson
+
+# sqlite.
+booking.db
+
+# Local runtime data (SQLite, keys, etc.)
+.data/
+
+# agr skills folders - controlled by agr.toml
+**/.cursor/
+**/.codex/
+**/.claude/
+**/.agents/
+**/.github/skills/
+**/.gemini/
+
+# Git worktrees
+.worktrees/
+
+# Scratch
+**/.scratch/
+
+# External reference repository checkouts (registry and structure stay tracked)
+external-repositories/*/public/*/
+external-repositories/*/private/*/

ryni-0.1.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: ryni
+Version: 0.1.0
+Summary: An opinionated linter for agent harnesses
+Requires-Python: >=3.14
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: pyyaml>=6
+Requires-Dist: typer>=0.20
+Description-Content-Type: text/markdown
+
+# Rýni
+
+**An opinionated linter for agent harnesses, written in Python.**
+
+[Getting started](#getting-started) · [Usage](#usage) · [Rules](#rules) · [Plugins](#plugins) · [Contributing](#contributing)
+
+Agent instructions and skills are part of your codebase. Rýni helps you keep them
+consistent as your project grows, enforcing conventions for how harnesses are
+structured, shared, and maintained, with actionable diagnostics when they drift.
+
+- **Validate skills.** Check `SKILL.md` frontmatter for required metadata.
+- **Keep instructions in sync.** Check that `CLAUDE.md` links to its sibling `AGENTS.md`.
+- **Check skill organization.** Find misplaced skill sources, tracked installations,
+  and missing or inconsistent local installations.
+- **Choose your rules.** Run the full catalog or select individual checks by ID.
+- **Use it in automation.** Get structured JSON output and predictable exit codes.
+- **Add your own conventions.** Distribute custom rules as Python packages.
+
+Rýni's built-in checks run locally, without a model or API key, and do not modify
+files. The project is in early development; the CLI and plugin API may change.
+
+## Getting started
+
+Rýni requires **Python 3.14 or later**. Git is required for the installed-skills
+ignore check (`SKILL002`).
+
+Install from PyPI with uv:
+
+```bash
+uv tool install ryni
+```
+
+Or with pip:
+
+```bash
+pip install ryni
+```
+
+Then run Rýni in the project you want to check:
+
+```bash
+ryni check .
+```
+
+## Usage
+
+Check files, directories, or multiple paths:
+
+```bash
+ryni check .
+ryni check skills/ AGENTS.md CLAUDE.md
+```
+
+List available rules:
+
+```bash
+ryni rule
+```
+
+Produce JSON for scripts and CI:
+
+```bash
+ryni check . --output-format json
+```
+
+The JSON report contains `checked_files`, `findings`, and `errors`. Each finding
+includes a path, line number, rule ID, and message. For repository-wide checks,
+`checked_files` also includes repository roots.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Checks completed without findings. |
+| `1` | Checks completed with findings. |
+| `2` | Invalid invocation, execution error, or incomplete checks. |
+
+Reports preserve findings when another check fails. Runs with no applicable targets
+explicitly report zero checked targets.
+
+### Configuration and discovery
+
+All registered rules, including installed plugins, run by default. Use `--select`
+to choose a comma-separated list of rule IDs. Configuration is currently through
+CLI options; Rýni does not read a configuration file.
+
+File rules search the supplied paths recursively and select files by name.
+Discovery skips `.git`, `.venv`, `venv`, `node_modules`, `__pycache__`, `.agents`,
+`.claude`, `.codex`, and `.github`. You can check those locations by passing them
+explicitly. Directory symlinks are not traversed, and repeated paths are deduplicated
+without resolving symlinks. File discovery does not apply `.gitignore` patterns.
+
+Repository rules inspect the nearest enclosing Git checkout for each supplied
+path, once per repository. Outside a Git checkout, they use the supplied directory
+or the file's parent directory. **Selecting a single file does not narrow the scope
+of repository rules.** Select only file rules when you want checks limited to those paths.
+
+## Rules
+
+Rýni includes five deterministic rules:
+
+| ID | Name | Checks |
+| --- | --- | --- |
+| `SKILL001` | `skill-frontmatter` | `SKILL.md` starts with valid YAML frontmatter containing non-empty string `name` and `description` fields. |
+| `AGENT001` | `claude-agents-symlink` | Each existing `CLAUDE.md` is a symlink resolving to an existing sibling `AGENTS.md`. |
+| `SKILL002` | `installed-skills-gitignored` | Installed skill directories for configured agents are covered by repository `.gitignore` rules and are not tracked. |
+| `SKILL003` | `local-skills-source-location` | Locally owned skills live under a directory named `skills/`, with nested categories allowed. |
+| `SKILL004` | `local-skills-installed` | Local skills have a matching local-source `skills-lock.json` entry and matching installed `SKILL.md` files for agents configured in their source scope. |
+
+`SKILL001` allows additional frontmatter fields and checks structure only.
+`AGENT001` allows `AGENTS.md` without a corresponding `CLAUDE.md`. `SKILL004`
+accepts copies and symlinks and checks installation evidence, not command history.
+
+These rules express Rýni’s opinions about maintaining agent harnesses. They do not assess
+instruction quality or agent behavior. Semantic and hybrid rule kinds are reserved
+for future use; agent execution is not implemented.
+
+## Plugins
+
+Extend Rýni with rules for your team's conventions. A Python package can export a
+`ryni.models.Rule` instance through the `ryni.rules` entry-point group.
+
+In the plugin's `pyproject.toml`:
+
+```toml
+[project.entry-points."ryni.rules"]
+example = "my_rules:EXAMPLE"
+```
+
+In `my_rules.py`:
+
+```python
+from pathlib import Path
+
+from ryni.models import Finding, Rule, RuleKind
+
+
+def check_readme(path: Path) -> list[Finding]:
+    if not path.read_text(encoding="utf-8").strip():
+        return [Finding(str(path), 1, "CUSTOM001", "README must not be empty.")]
+    return []
+
+
+EXAMPLE = Rule(
+    id="CUSTOM001",
+    name="nonempty-readme",
+    kind=RuleKind.DETERMINISTIC,
+    description="README.md must contain text.",
+    filename="README.md",
+    evaluate=check_readme,
+)
+```
+
+Install the plugin in the same Python environment as Rýni. Both `check` and `rule`
+load installed plugins; duplicate rule IDs are rejected. Plugins execute Python
+code, so only install packages you trust.
+
+Evaluators receive a path and return a list of findings. They must not print or
+modify files. An evaluator exception produces an execution error and exit code `2`,
+while other checks continue.
+
+## Contributing
+
+Bug reports, rule proposals, documentation improvements, and pull requests are
+welcome. For a bug report, include the command you ran, a minimal example, and the
+expected and actual output. For a new rule, describe the convention it checks and
+show examples that should pass and fail.
+
+Rýni currently lives in `tools/ryni` in this repository. From the repository root:
+
+```bash
+uv run ryni --help
+uv run pytest tools/ryni/tests
+uv run ruff check tools/ryni
+```
+
+The [CLI](src/ryni/cli.py) handles commands and output, the
+[engine](src/ryni/engine.py) discovers targets and runs checks, and the
+[rule catalog](src/ryni/rules/__init__.py) registers built-in rules and loads plugins.
+Add built-in rules under `src/ryni/rules/`, register them in `BUILTINS`, and include
+tests under `tests/`.

ryni-0.1.0/README.md

@@ -0,0 +1,179 @@
+# Rýni
+
+**An opinionated linter for agent harnesses, written in Python.**
+
+[Getting started](#getting-started) · [Usage](#usage) · [Rules](#rules) · [Plugins](#plugins) · [Contributing](#contributing)
+
+Agent instructions and skills are part of your codebase. Rýni helps you keep them
+consistent as your project grows, enforcing conventions for how harnesses are
+structured, shared, and maintained, with actionable diagnostics when they drift.
+
+- **Validate skills.** Check `SKILL.md` frontmatter for required metadata.
+- **Keep instructions in sync.** Check that `CLAUDE.md` links to its sibling `AGENTS.md`.
+- **Check skill organization.** Find misplaced skill sources, tracked installations,
+  and missing or inconsistent local installations.
+- **Choose your rules.** Run the full catalog or select individual checks by ID.
+- **Use it in automation.** Get structured JSON output and predictable exit codes.
+- **Add your own conventions.** Distribute custom rules as Python packages.
+
+Rýni's built-in checks run locally, without a model or API key, and do not modify
+files. The project is in early development; the CLI and plugin API may change.
+
+## Getting started
+
+Rýni requires **Python 3.14 or later**. Git is required for the installed-skills
+ignore check (`SKILL002`).
+
+Install from PyPI with uv:
+
+```bash
+uv tool install ryni
+```
+
+Or with pip:
+
+```bash
+pip install ryni
+```
+
+Then run Rýni in the project you want to check:
+
+```bash
+ryni check .
+```
+
+## Usage
+
+Check files, directories, or multiple paths:
+
+```bash
+ryni check .
+ryni check skills/ AGENTS.md CLAUDE.md
+```
+
+List available rules:
+
+```bash
+ryni rule
+```
+
+Produce JSON for scripts and CI:
+
+```bash
+ryni check . --output-format json
+```
+
+The JSON report contains `checked_files`, `findings`, and `errors`. Each finding
+includes a path, line number, rule ID, and message. For repository-wide checks,
+`checked_files` also includes repository roots.
+
+| Exit code | Meaning |
+| --- | --- |
+| `0` | Checks completed without findings. |
+| `1` | Checks completed with findings. |
+| `2` | Invalid invocation, execution error, or incomplete checks. |
+
+Reports preserve findings when another check fails. Runs with no applicable targets
+explicitly report zero checked targets.
+
+### Configuration and discovery
+
+All registered rules, including installed plugins, run by default. Use `--select`
+to choose a comma-separated list of rule IDs. Configuration is currently through
+CLI options; Rýni does not read a configuration file.
+
+File rules search the supplied paths recursively and select files by name.
+Discovery skips `.git`, `.venv`, `venv`, `node_modules`, `__pycache__`, `.agents`,
+`.claude`, `.codex`, and `.github`. You can check those locations by passing them
+explicitly. Directory symlinks are not traversed, and repeated paths are deduplicated
+without resolving symlinks. File discovery does not apply `.gitignore` patterns.
+
+Repository rules inspect the nearest enclosing Git checkout for each supplied
+path, once per repository. Outside a Git checkout, they use the supplied directory
+or the file's parent directory. **Selecting a single file does not narrow the scope
+of repository rules.** Select only file rules when you want checks limited to those paths.
+
+## Rules
+
+Rýni includes five deterministic rules:
+
+| ID | Name | Checks |
+| --- | --- | --- |
+| `SKILL001` | `skill-frontmatter` | `SKILL.md` starts with valid YAML frontmatter containing non-empty string `name` and `description` fields. |
+| `AGENT001` | `claude-agents-symlink` | Each existing `CLAUDE.md` is a symlink resolving to an existing sibling `AGENTS.md`. |
+| `SKILL002` | `installed-skills-gitignored` | Installed skill directories for configured agents are covered by repository `.gitignore` rules and are not tracked. |
+| `SKILL003` | `local-skills-source-location` | Locally owned skills live under a directory named `skills/`, with nested categories allowed. |
+| `SKILL004` | `local-skills-installed` | Local skills have a matching local-source `skills-lock.json` entry and matching installed `SKILL.md` files for agents configured in their source scope. |
+
+`SKILL001` allows additional frontmatter fields and checks structure only.
+`AGENT001` allows `AGENTS.md` without a corresponding `CLAUDE.md`. `SKILL004`
+accepts copies and symlinks and checks installation evidence, not command history.
+
+These rules express Rýni’s opinions about maintaining agent harnesses. They do not assess
+instruction quality or agent behavior. Semantic and hybrid rule kinds are reserved
+for future use; agent execution is not implemented.
+
+## Plugins
+
+Extend Rýni with rules for your team's conventions. A Python package can export a
+`ryni.models.Rule` instance through the `ryni.rules` entry-point group.
+
+In the plugin's `pyproject.toml`:
+
+```toml
+[project.entry-points."ryni.rules"]
+example = "my_rules:EXAMPLE"
+```
+
+In `my_rules.py`:
+
+```python
+from pathlib import Path
+
+from ryni.models import Finding, Rule, RuleKind
+
+
+def check_readme(path: Path) -> list[Finding]:
+    if not path.read_text(encoding="utf-8").strip():
+        return [Finding(str(path), 1, "CUSTOM001", "README must not be empty.")]
+    return []
+
+
+EXAMPLE = Rule(
+    id="CUSTOM001",
+    name="nonempty-readme",
+    kind=RuleKind.DETERMINISTIC,
+    description="README.md must contain text.",
+    filename="README.md",
+    evaluate=check_readme,
+)
+```
+
+Install the plugin in the same Python environment as Rýni. Both `check` and `rule`
+load installed plugins; duplicate rule IDs are rejected. Plugins execute Python
+code, so only install packages you trust.
+
+Evaluators receive a path and return a list of findings. They must not print or
+modify files. An evaluator exception produces an execution error and exit code `2`,
+while other checks continue.
+
+## Contributing
+
+Bug reports, rule proposals, documentation improvements, and pull requests are
+welcome. For a bug report, include the command you ran, a minimal example, and the
+expected and actual output. For a new rule, describe the convention it checks and
+show examples that should pass and fail.
+
+Rýni currently lives in `tools/ryni` in this repository. From the repository root:
+
+```bash
+uv run ryni --help
+uv run pytest tools/ryni/tests
+uv run ruff check tools/ryni
+```
+
+The [CLI](src/ryni/cli.py) handles commands and output, the
+[engine](src/ryni/engine.py) discovers targets and runs checks, and the
+[rule catalog](src/ryni/rules/__init__.py) registers built-in rules and loads plugins.
+Add built-in rules under `src/ryni/rules/`, register them in `BUILTINS`, and include
+tests under `tests/`.

ryni-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling>=1.18"]
+build-backend = "hatchling.build"
+
+[project]
+name = "ryni"
+version = "0.1.0"
+description = "An opinionated linter for agent harnesses"
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "typer>=0.20",
+    "pyyaml>=6",
+    "pydantic>=2.13.5",
+]
+
+[project.scripts]
+ryni = "ryni.cli:app"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/ryni"]

ryni-0.1.0/src/ryni/__init__.py

@@ -0,0 +1 @@
+"""Rýni: rule-based linting for agent harnesses."""

ryni-0.1.0/src/ryni/cli.py

@@ -0,0 +1,69 @@
+import json
+from dataclasses import asdict
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from ryni.engine import check as run_checks
+from ryni.rules import CatalogLoadError, RuleCatalog, UnknownRulesError, load_catalog
+
+app = typer.Typer(help="Rýni: rule-based linting for agent harnesses.", no_args_is_help=True)
+
+
+class OutputFormat(StrEnum):
+    TEXT = "text"
+    JSON = "json"
+
+
+def available_rules() -> RuleCatalog:
+    try:
+        return load_catalog()
+    except CatalogLoadError as error:
+        typer.echo(f"Error loading rules: {error}", err=True)
+        raise typer.Exit(2) from error
+
+
+@app.command()
+def check(
+    paths: Annotated[list[Path], typer.Argument(help="Files or directories to check.")],
+    select: Annotated[str | None, typer.Option(help="Comma-separated rule IDs.")] = None,
+    output_format: Annotated[OutputFormat, typer.Option(help="Diagnostic output format.")] = (
+        OutputFormat.TEXT
+    ),
+) -> None:
+    """Check selected paths. Exit 0: clean, 1: findings, 2: error/incomplete."""
+    catalog = available_rules()
+    try:
+        rules = catalog.select(select.split(",") if select is not None else None)
+    except UnknownRulesError as error:
+        raise typer.BadParameter(str(error), param_hint="--select") from error
+    result = run_checks(paths, rules)
+    if output_format == OutputFormat.JSON:
+        typer.echo(json.dumps(asdict(result), indent=2))
+    else:
+        for finding in result.findings:
+            typer.echo(f"{finding.path}:{finding.line}: {finding.rule_id} {finding.message}")
+        for error in result.errors:
+            typer.echo(f"Error: {error}", err=True)
+        typer.echo(
+            f"Checked {len(result.checked_files)} targets · {len(result.findings)} findings · "
+            f"{len(result.errors)} errors"
+        )
+    raise typer.Exit(result.exit_code)
+
+
+@app.command()
+def rule(rule_id: Annotated[str | None, typer.Argument(help="Rule ID to explain.")] = None) -> None:
+    """List rules, or explain one rule with an example."""
+    catalog = available_rules()
+    if rule_id is None:
+        for item in catalog.select():
+            typer.echo(f"{item.id}  {item.name}  [{item.kind}]")
+        return
+    try:
+        item = catalog.get(rule_id)
+    except UnknownRulesError as error:
+        raise typer.BadParameter(str(error)) from error
+    typer.echo(f"{item.id}: {item.name} [{item.kind}]\n\n{item.description}")

ryni-0.1.0/src/ryni/engine.py

@@ -0,0 +1,88 @@
+import os
+from collections.abc import Sequence
+from pathlib import Path
+
+from ryni.models import CheckResult, Finding, Rule, RuleScope
+from ryni.skill_repository_local import repository_root
+
+EXCLUDED_DIRECTORIES = {
+    ".git",
+    ".venv",
+    "venv",
+    "node_modules",
+    "__pycache__",
+    ".agents",
+    ".claude",
+    ".codex",
+    ".github",
+}
+
+
+def discover(paths: list[Path], result: CheckResult) -> list[Path]:
+    files: dict[Path, Path] = {}
+    for path in paths:
+        if path.is_file() or path.is_symlink():
+            files.setdefault(path.absolute(), path)
+        elif path.is_dir():
+            files.setdefault(path.absolute(), path)
+            for root, directories, names in os.walk(
+                path, onerror=lambda error: result.errors.append(str(error))
+            ):
+                directories[:] = sorted(
+                    name for name in directories if name not in EXCLUDED_DIRECTORIES
+                )
+                # Preserve named directories too: a directory named CLAUDE.md is invalid.
+                for name in sorted(names + directories):
+                    candidate = Path(root) / name
+                    files.setdefault(candidate.absolute(), candidate)
+        else:
+            result.errors.append(f"Path does not exist or is not a regular file/directory: {path}")
+    return sorted(files.values(), key=str)
+
+
+def check(paths: list[Path], rules: Sequence[Rule]) -> CheckResult:
+    result = CheckResult()
+    repository_rules = [rule for rule in rules if rule.scope == RuleScope.REPOSITORY]
+    file_rules = [rule for rule in rules if rule.scope == RuleScope.FILE]
+    if repository_rules:
+        roots = {repository_root(path) for path in paths if path.exists()}
+        for root in sorted(roots):
+            _evaluate(root, repository_rules, result)
+    for path in discover(paths, result):
+        applicable = [rule for rule in file_rules if path.name == rule.filename]
+        if not applicable:
+            continue
+        _evaluate(path, applicable, result)
+    return result
+
+
+def _evaluate(path: Path, rules: Sequence[Rule], result: CheckResult) -> None:
+    complete = True
+    for rule in rules:
+        try:
+            findings = _validated_findings(rule.evaluate(path), rule.id)
+            result.findings.extend(findings)
+        except Exception as error:
+            result.errors.append(f"Cannot check {path} with {rule.id}: {error}")
+            complete = False
+    if complete:
+        result.checked_files.append(str(path))
+
+
+def _validated_findings(output: object, rule_id: str) -> list[Finding]:
+    if not isinstance(output, list):
+        raise ValueError("Rule must return a list of Finding objects")
+    validated: list[Finding] = []
+    for finding in output:
+        if not isinstance(finding, Finding):
+            raise ValueError("Rule must return a list of Finding objects")
+        if not all(
+            isinstance(value, str) for value in (finding.path, finding.rule_id, finding.message)
+        ):
+            raise ValueError("Finding path, rule_id, and message must be strings")
+        if type(finding.line) is not int or finding.line < 1:
+            raise ValueError("Finding line must be a positive integer")
+        if finding.rule_id != rule_id:
+            raise ValueError(f"Finding rule_id must match {rule_id}")
+        validated.append(finding)
+    return validated

ryni-0.1.0/src/ryni/models.py

@@ -0,0 +1,45 @@
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from enum import StrEnum
+from pathlib import Path
+
+
+class RuleKind(StrEnum):
+    DETERMINISTIC = "deterministic"
+    SEMANTIC = "semantic"
+    HYBRID = "hybrid"
+
+
+class RuleScope(StrEnum):
+    FILE = "file"
+    REPOSITORY = "repository"
+
+
+@dataclass(frozen=True)
+class Finding:
+    path: str
+    line: int
+    rule_id: str
+    message: str
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    name: str
+    kind: RuleKind
+    description: str
+    filename: str
+    evaluate: Callable[[Path], list[Finding]]
+    scope: RuleScope = RuleScope.FILE
+
+
+@dataclass
+class CheckResult:
+    checked_files: list[str] = field(default_factory=list)
+    findings: list[Finding] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+
+    @property
+    def exit_code(self) -> int:
+        return 2 if self.errors else int(bool(self.findings))