Skip to content

AGENTS.md

Latest commit

 

History

History
139 lines (102 loc) · 2.8 KB

AGENTS.md

File metadata and controls

139 lines (102 loc) · 2.8 KB

AGENTS.md - AI Contributor Guide

Welcome, AI agent! This file helps you understand how to contribute to this repo.

Quick Start

# Clone and setup
git clone https://github.com/Olafs-World/my-tool.git
cd my-tool
uv sync

# Run tests
uv run pytest

# Run linter
uv run ruff check .

Code Style

  • Formatter: ruff (configured in pyproject.toml)
  • Type hints: Preferred but not required
  • Docstrings: Google style
  • Tests: pytest, aim for >80% coverage

Git Commits

For Olafs-World repos, set Aaron as author and add bot co-author:

git config user.name "Aaron Levin"
git config user.email "awlevin@comcast.net"

Commit message format:

Short summary (50 chars or less)

Longer description if needed. Wrap at 72 characters.

Co-authored-by: olaf-s-app[bot] <259723076+olaf-s-app[bot]@users.noreply.github.com>

Release Process

⚠️ NEVER manually publish to PyPI! Always use git tags - CI handles publishing.

Steps to Release

  1. Bump version in pyproject.toml:

    version = "X.Y.Z"

  2. Update CHANGELOG.md:

    ## [X.Y.Z] - YYYY-MM-DD
### Added
- New feature description
### Fixed
- Bug fix description

  3. Commit changes:

    git add -A
git commit -m "Bump version to X.Y.Z"

  4. Tag and push:

    git tag vX.Y.Z
git push && git push --tags

  5. CI auto-publishes to PyPI when the tag is pushed.

Why Not Manual Publishing?

Manual uv publish or twine upload causes:

  • GitHub releases and PyPI versions to get out of sync
  • Missing release notes on GitHub
  • Confusion about what's actually deployed

The tag-based workflow ensures everything stays synchronized.

Project Structure

├── my_tool/
│   ├── __init__.py      # Version and package info
│   ├── cli.py           # Click-based CLI entry point
│   └── core.py          # Business logic (keep CLI thin)
├── tests/
│   ├── test_cli.py      # CLI tests (invoke runner)
│   └── test_core.py     # Unit tests for core logic
├── AGENTS.md            # This file
├── SKILL.md             # ClawHub skill definition
├── CHANGELOG.md         # Release history
└── pyproject.toml       # Package config

Testing

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=my_tool

# Skip integration tests (if any)
uv run pytest -m "not integration"

Mark slow/external tests:

@pytest.mark.integration
def test_external_api():
    ...

ClawHub Publishing

After PyPI release, update ClawHub:

clawhub publish .

Or if the skill is in a subdirectory:

clawhub publish skills/my-tool/

Questions?

Check existing code patterns in the repo. When in doubt, keep it simple.