autograde

Imported from zeref-sv00/autograde (AGENTS.md). Install upstream with npx skills add zeref-sv00/autograde. Copyright stays with the author.

AGENTS.md

Repository-level instructions for AI coding agents working on this project.

Project purpose

autograde is a command-line tool that inspects a target Git repository and reports whether a set of required conditions hold. The set of checks is defined in specs/spec-001-autograde.md. Read that spec before changing behavior.

Workflow

• Use uv for dependency management. Do not edit uv.lock by hand.
• To add a runtime dependency: uv add <package>.
• To add a dev dependency: uv add --dev <package>.
• Use pytest for testing. Run the suite with uv run pytest.
• Follow Spec-Driven Development: if behavior changes, update specs/spec-001-autograde.md in the same commit, before touching code.
• Follow Test-Driven Development: write or update tests in tests/ first, see them fail, then implement.

Conventions

• Prefer behavioral tests over implementation-detail tests. Tests should exercise the public surface (autograde.checks.<function> and the CLI), not private helpers.
• All Git interaction MUST go through subprocess against the git binary. Do not add GitPython, pygit2, or similar dependencies.
• Each check lives as a pure function in src/autograde/checks.py. The CLI in src/autograde/cli.py only orchestrates; it does not contain Git logic.
• Tests MUST build their own throwaway repositories under tempfile.TemporaryDirectory. They MUST NOT touch any directory outside the test's own temp directory, and MUST NOT depend on network access.
• Keep patches small. One spec change, one feature, one commit when possible.

Out of scope

• Network access of any kind (no requests, no urllib, no GitHub API calls).
• Mutating the target repository. autograde is strictly read-only.
• Adding configuration files for tools that are not in use (no mypy.ini, no .pre-commit-config.yaml, etc.) unless the user explicitly asks for them.

How to verify your work

Before declaring a task done:

1. uv run pytest must finish with all tests passing.
2. uv run autograde . must run without crashing when executed from the project root (some checks may legitimately FAIL on this very repository; that's fine, what matters is that the tool runs).
3. If you changed behavior, the spec in specs/ must reflect it.