Skip to content

AGENTS.md

Latest commit

 

History

History
153 lines (109 loc) · 4.94 KB

AGENTS.md

File metadata and controls

153 lines (109 loc) · 4.94 KB
Raw

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Repository Overview

This is a collection of standalone utility scripts (Python and Bash) for common development and system administration tasks. Scripts are designed to be self-contained and executable directly from the repository directory or from the PATH.

Script Documentation Convention

All scripts in this repository follow a tag-based documentation format at the top of each file:

# BRIEF: <one-line-summary>
# DESC: <optional-longer-explanation>
# DESC: <continuation-lines-repeat-the-tag>
# USAGE: <optional-usage-examples>
# DEPS: <optional-external-dependencies>

Key Rules:

  • BRIEF is required (< 80 chars)
  • DESC, USAGE, DEPS are optional
  • Multi-line tags repeat the prefix on each line
  • Placement: Within first ~10 lines, after shebang and any embedded metadata
  • Use imperative mood: "Print paths" not "Prints paths"

See docs/documentation.md for complete guidelines.

Python Scripts with UV

Many Python scripts use uv as a script runner with embedded dependencies:

#!/usr/bin/env -S uv run --quiet --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
#    "click",
#    "rich",
# ]
# ///
# BRIEF: Script description here

This allows scripts to be standalone with their dependencies specified inline. The uv tool handles creating isolated environments and installing packages automatically.

Python Click Scripts:

  • When using Click, enable -h as a help option alias by adding context_settings={"help_option_names": ["-h", "--help"]} to the command/group decorator

Bash scripts

Bash scripts do not state the path to bash directly:

#!/usr/bin/env bash
# BRIEF: Script description here

Architecture

Structure:

  • src/ contains all executable scripts
  • src/ARCHIVE/ contains old/deprecated scripts (excluded from normal operations)
  • docs/ contains documentation
  • No build system - scripts are run directly

Generated files (do not edit by hand):

  • The "Contents" section of README.md is generated by cog from the scripts' BRIEF tags - regenerate with mise run docs
  • manifest.json lists all scripts with their type - regenerate with mise run generate-manifest

Maintenance Tasks

Maintenance is driven by mise (see mise.toml):

mise run lint-all            # shellcheck + ruff check + ruff format --check
mise run sh-lint             # shellcheck on bash scripts
mise run python-lint         # ruff check on Python scripts
mise run python-format       # ruff format on Python scripts
mise run python-fix          # ruff check --fix on Python scripts
mise run docs                # regenerate README.md contents with cog
mise run generate-manifest   # regenerate manifest.json

After adding or modifying a script, run mise run lint-all. After adding a script or changing a BRIEF tag, also run mise run generate-manifest and mise run docs.

Running Scripts

Scripts are executed directly:

./src/script-name [args]

For Python scripts using uv, the first run will install dependencies. Subsequent runs use cached environments.

Adding New Scripts

When creating a new script:

  1. Make it executable: chmod +x script-name
  2. Add appropriate shebang:
    • Bash: #!/usr/bin/env bash
    • Python with uv: #!/usr/bin/env -S uv run --quiet --script
  3. Add documentation tags (BRIEF at minimum)
  4. For Python scripts with dependencies, use uv PEP 723 inline metadata
  5. Place in src/ (not in further subdirectories)
  6. Validate docs (./src/script-docs dump --strict src/script-name), lint (mise run lint-all), and regenerate manifest.json and README.md (mise run generate-manifest && mise run docs)

Validating and Extracting Documentation

The script-docs tool extracts and validates documentation from scripts:

The tool takes file paths, not bare script names.

Validate documentation:

./src/script-docs dump --strict src/script-name

Extract documentation in various formats:

# JSON (array format)
./src/script-docs dump src/script-name [src/script-name2 ...]

# Markdown (raw)
./src/script-docs dump --format markdown src/script-name

# Rich (rendered in terminal)
./src/script-docs dump --format rich src/script-name

# README format (brief list)
./src/script-docs dump --format readme src/*

Common validation issues:

  • Missing BRIEF tag (required)
  • Missing shebang (files without #! are skipped)
  • Non-script files are automatically filtered out

Use --strict mode when adding or modifying scripts to ensure documentation is complete.

Code Preservation when documenting with comments

Critical: When modifying scripts, preserve all existing code including:

  • __description__ variables in Python scripts
  • Docstrings and inline comments
  • Function implementations
  • Any existing functionality

Only update documentation headers, never remove working code during documentation updates.