plex-playlist/docs/POE_TASK_REFERENCE.md

Poe the Poet Task Reference

This project uses Poe the Poet as a unified task runner to simplify development workflows. All tasks are defined in backend/pyproject.toml and can be run from the project root.

🚀 Quick Start

# Install dependencies and set up development environment
poe setup

# See all available tasks
poe --help

# Interactive task selection
poe

📋 Essential Tasks

Development Environment

poe dev              # Start development environment (Docker Compose)
poe dev-down         # Stop development environment
poe dev-logs         # Follow development logs
poe dev-restart      # Restart development environment

Code Quality (Unified Backend + Frontend)

poe format           # Format all code (Python + TypeScript)
poe lint             # Lint all code (Python + TypeScript)
poe type-check       # Type check all code (Python + TypeScript)

Testing

poe test-unit        # Run all unit tests (backend + frontend)
poe test-all         # Run all tests including integration
poe test-full        # Run all tests with coverage + E2E
poe test-e2e         # Run end-to-end tests only

CI/CD Pipeline

poe ci-quick         # Fast quality checks (format, lint, type-check)
poe ci-full          # Complete CI pipeline simulation
poe quality-gate     # All quality checks (like CI)

Docker Images

poe build-cicd       # Build both base and complete CI/CD images
poe build-cicd-base  # Build only base image (cached dependencies)
poe build-cicd-complete  # Build only complete image (fast)

🏃‍♂️ Performance Tasks (Parallel Execution)

poe lint-parallel         # Run linting in parallel for speed
poe type-check-parallel   # Run type checking in parallel
poe test-parallel         # Run tests in parallel

🧠 Smart Tasks (Conditional Execution)

poe test-if-changed       # Only test if code changed
poe build-if-dockerfile-changed  # Only build if Dockerfiles changed

🛠 Utility Tasks

poe deps-install     # Install all dependencies (backend + frontend)
poe deps-update      # Update all dependencies
poe clean            # Clean build artifacts and caches
poe reset            # Complete reset (clean + reinstall)

🔧 Individual Component Tasks

Backend Only

poe format-backend       # Format Python code only
poe lint-backend         # Lint Python code only
poe type-check-backend   # Type check Python only
poe test-backend         # Run backend tests only
poe test-backend-cov     # Backend tests with coverage

Frontend Only

poe format-frontend      # Format TypeScript code only
poe lint-frontend        # Lint TypeScript code only
poe type-check-frontend  # Type check TypeScript only
poe test-frontend        # Run frontend tests only
poe test-frontend-cov    # Frontend tests with coverage

📚 Documentation Tasks

poe docs-backend     # Run docstring tests
poe docs-check       # Check docstring quality

🎣 Pre-commit Integration

poe pre-commit-install   # Install pre-commit hooks
poe pre-commit-run       # Run all pre-commit hooks
poe pre-commit-update    # Update hook versions

💡 Tips & Tricks

Task Discovery

poe --help           # List all tasks with descriptions
poe <task> --help    # Get help for specific task
poe                  # Interactive task picker

Chaining Tasks

# Run multiple tasks in sequence
poe format lint type-check test-unit

# Custom workflows
poe clean deps-install ci-quick

Environment Context

• All tasks run from project root
• Backend tasks automatically use uv run in correct environment
• Frontend tasks automatically use yarn in correct directory
• Docker tasks use the optimized multi-stage CI/CD setup

Performance Tips

• Use parallel tasks (*-parallel) for faster feedback
• Use conditional tasks (*-if-changed) to save time
• poe setup configures everything for new developers
• poe quality-gate runs full CI checks locally

🔄 Migration from Manual Commands

Before (Manual)

cd backend && uv run ruff format .
cd frontend && yarn prettier --write src/
cd backend && uv run pytest
cd frontend && yarn test
./scripts/build-cicd-local.sh

After (Poe)

poe format
poe test-unit
poe build-cicd

🏗 Integration with Existing Workflows

• Pre-commit hooks: Still work as before, Poe complements them
• CI/CD pipeline: Uses same tools, Poe provides local simulation
• Docker development: poe dev replaces manual docker-compose commands
• Scripts: Existing scripts still work, Poe provides unified interface

🎯 Next Steps

1. Try it out: poe setup to get started
2. Explore tasks: poe --help to see all options
3. Customize: Add project-specific tasks to backend/pyproject.toml
4. Share: Team members can use same unified interface

This unified task system makes development faster, more consistent, and easier for new team members to learn!