<!--
SPDX-License-Identifier: AGPL-3.0-or-later
SPDX-FileCopyrightText: Copyright 2023 David Seaward and contributors
-->

# Tardyon: Agent Guidelines

## Core Principles

- **No Runtime Dependencies**: The project must only depend on the Python standard library. No external packages (e.g., `requests`, `click`) should be added to `[project.dependencies]`.

- **Type Hints**: Use type hints for all function signatures.

- **Process Replacement**: The CLI uses `os.execv` to replace the current process with the target script. Do not switch to `subprocess.run` unless the task explicitly requires returning control to the Python process.

- **Dynamic Versioning**: Versioning is managed via `hatch-vcs`. Do not hardcode version strings in `pyproject.toml` or `src/tardyon/cli.py`.

## Directory Conventions

- Scripts are stored at `$HOME/.local/bin/tardy/{noun}/{verb}.{noun}`.

- For a command `tardyon foo bar`, the path is `.../tardy/bar/foo.bar`.

- The "show yourself" command must handle cross-platform directory opening.

## Licensing & Standards

- **REUSE Compliance**: All files must include appropriate SPDX license and copyright headers.

- **Python Version**: Support Python 3.10 and newer.

## Testing

- Use `pytest`.

- Mock `os.execv`, `sys.exit`, and `pathlib.Path.home` when testing CLI logic to avoid side effects.

- Test both script existence and executability checks in `launch_tardyon_script`.
