## Stack and Commands

**Language:** Python 3.8+
**Package manager:** uv / pip (`.venv/`)
**Test runner:** pytest
**Linter/formatter:** flake8 (100-char), black (88-char), mypy (strict)

### Essential commands

```bash
make setup-complete     # First-time setup: venv + package + dev deps
source .venv/bin/activate
make test               # Run full test suite
make lint               # flake8 linting
make format             # black formatting
make clean              # Remove build artifacts
```

### TDD workflow

```bash
make tdd-start ISSUE=X  # Start issue with requirements validation
make tdd-add-test       # Add test to current workspace
make tdd-status         # Show workspace state
make tdd-finish         # Move tests to main suite
```

### Issue management

```bash
make issue-list         # All issues (Gitea)
make issue-list-open    # Open backlog
make issue-show ISSUE=X # Issue detail
make issue-create TITLE='...' BODY='...'
```

Run `make help` to see all available targets.

### Core dependencies (pyproject.toml)

- `pyyaml>=6.0` — YAML config
- `click>=8.0.0` — CLI framework
- `pydantic>=2.0.0` — Data validation