agent-ready: Instructions file for Claude Code

CLAUDE.md — agent-ready

Critical Commands

Use only these commands. Never invent alternatives or substitute similar-looking tools.

# Install (end-user, with LLM support)
pip install "git+https://github.com/vb-nattamai/agent-ready.git[ai]"

# Build (development, editable install with dev extras)
pip install -e '.[dev]'

# Test (must pass with ≥50% coverage — do not relax the threshold)
pytest -q --cov=src/agent_ready --cov-report=term-missing --cov-fail-under=50

# Run (transform a target repository)
agent-ready --target /path/to/repo

# Lint check
ruff check src/agent_ready tests

# Format check (do not auto-apply in CI)
ruff format --check src/agent_ready tests

# Dry-run (preview generated files without writing)
agent-ready --target /path/to/repo --dry-run

# Evaluate existing context files without regenerating
agent-ready --target /path/to/repo --eval-only

Always Do

1. Set PYTHONPATH when running tests locally if imports fail: PYTHONPATH=src pytest -q .... The package lives under src/agent_ready/ and uses the src layout declared in pyproject.toml.

2. Keep src/agent_ready/__init__.py and the VERSION file in sync. The __version__ string in __init__.py is the authoritative source read by setuptools dynamic versioning; VERSION must match. The release workflow manages this automatically — if you touch either file manually, update both.

3. Add tests under tests/ for any new code in src/agent_ready/. The CI gate is --cov-fail-under=50; new untested code will fail the pipeline. Mirror the module path: code in src/agent_ready/evaluator.py → tests in tests/test_evaluator.py.

4. Mock LLM calls at the retry-wrapper level in tests, not at the raw litellm.completion level. Because analyser.py, generator.py, and evaluator.py all wrap LLM calls with exponential-backoff retry logic for 429/529/overloaded errors, mocking only litellm.completion may not intercept at the right point. Verify your mock actually short-circuits the retry loop.