Skip to content

AGENTS.md

Latest commit

 

History

History
67 lines (51 loc) · 2.2 KB

AGENTS.md

File metadata and controls

67 lines (51 loc) · 2.2 KB
Raw

AGENTS.md

Contributor rules for any AI or automation agent working on GForge (Python).

Read First

  1. README.md
  2. PLAN.md
  3. AGENTS.md

Project Scope

GForge is a secure global Git hooks installer for developer workstations. This repository is the Python port of psspl-gaurang/gforge; the original design and detection engine are the work of Gaurang Joshi, Shrey Tandel, and Dwij Acharya, who contributed to it equally.

Do not expand it into:

  • Full workstation provisioning
  • CI/CD tooling
  • Cloud or Kubernetes automation
  • Frontend, UI, design system, or branding work
  • Generated documentation or agent-skill systems

Working Rules

  • Keep docs and code token-friendly.
  • Prefer updating the existing root docs over adding new docs.
  • Do not invent commands, APIs, or scope.
  • Make install operations idempotent.
  • Make verify operations read-only.
  • Make uninstall remove only GForge-owned files and config.
  • Never store or print secrets.
  • Preserve the Apache 2.0 license and NOTICE, and keep the attribution to the original author intact in README.md and NOTICE.

Port-specific rules

  • Stay behaviour-compatible with upstream. The detection engine should agree with the Node implementation rule for rule. When a heuristic must diverge, document why in a comment and in the README's "Differences" table.
  • src/gforge/scanner.py must stay standard-library only and free of any gforge import. It is copied verbatim into ~/.gforge/hooks/ and has to run under an arbitrary interpreter. tests/test_hooks.py enforces this.
  • The scanner fails closed. Any error path must block the commit, never allow it through unscanned.
  • Zero runtime dependencies. Dev-only tools belong in [project.optional-dependencies].dev.
  • Support Python 3.9+; no syntax or stdlib API newer than that in shipped code.
  • Full type annotations; mypy --strict must pass.

Validation

Run all of these before proposing a change:

pytest
ruff check .
ruff format --check .
mypy
python -m build      # packaging must stay clean

For documentation-only work, check headings, stale references, empty files, and wording clarity.