Python Project Template

Python template to quickstart any project with production-ready workflow, quality tooling, and AI-assisted development.

Quick Start

# 1. Clone the template
git clone https://github.com/nullhack/python-project-template
cd python-project-template

# 2. Install UV package manager (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 3. Set up the development environment
uv sync --all-extras

# 4. Customize template placeholders for your project
opencode && @setup-project

# 5. Validate everything works
uv run task test && uv run task lint && uv run task static-check && timeout 10s uv run task run

What This Template Provides

Development Workflow

A 6-step Kanban workflow with WIP=1 (one feature at a time), enforced by the filesystem:

docs/features/backlog/       ← features waiting to be worked on
docs/features/in-progress/   ← exactly one feature being built
docs/features/completed/     ← accepted and shipped features

3 roles, 6 steps:

Step	Role	What happens
1. SCOPE	Product Owner	User stories + UUID acceptance criteria
2. BOOTSTRAP + ARCH	Developer	Build system, module structure, ADRs
3. TEST FIRST	Developer	Failing tests mapped 1:1 to UUID criteria
4. IMPLEMENT	Developer	Red→Green→Refactor, commit per green test
5. VERIFY	Reviewer	Run all commands, code review, UUID traceability
6. ACCEPT	Product Owner	Demo, validate, merge, tag

AI Agents

@product-owner   # Defines features, picks from backlog, accepts deliveries
@developer       # Architecture, tests, code, git, releases
@reviewer        # Runs commands, reviews code — read+bash only
@setup-project   # One-time template initialization

Skills

/skill session-workflow    # Read TODO.md, continue, hand off cleanly
/skill scope               # Write user stories + acceptance criteria
/skill tdd                 # TDD: file naming, docstring format, markers
/skill implementation      # Red-Green-Refactor, architecture, ADRs
/skill code-quality        # ruff, pyright, coverage, complexity limits
/skill verify              # Step 5 verification checklist
/skill pr-management       # Branch naming, PR template, squash merge
/skill git-release         # Hybrid calver versioning, themed naming
/skill create-skill        # Add new skills to the system

Development Commands

uv run task run              # Run the application (humans)
timeout 10s uv run task run  # Run with timeout (agents — exit 124 = hung = FAIL)
uv run task test             # Full test suite with coverage report
uv run task test-fast        # Tests without coverage (faster iteration)
uv run task test-slow        # Only slow tests
uv run task lint             # ruff check + format
uv run task static-check     # pyright type checking
uv run task doc-build        # Generate API docs + coverage + test reports
uv run task doc-publish      # Publish unified docs site to GitHub Pages
uv run task doc-serve        # Live API doc server at localhost:8080

Code Quality Standards

Standard	Target
Coverage	100%
Type checking	pyright, 0 errors
Linting	ruff, 0 issues, Google docstrings
Function length	≤ 20 lines
Class length	≤ 50 lines
Max nesting	2 levels
Principles	YAGNI > KISS > DRY > SOLID > Object Calisthenics

Test Conventions

def test_<short_title>():
    """a1b2c3d4-e5f6-7890-abcd-ef1234567890

    Given: precondition
    When: action
    Then: single observable outcome
    """
    # Given
    ...
    # When
    ...
    # Then
    ...

Markers: @pytest.mark.unit · @pytest.mark.integration · @pytest.mark.slow

Technology Stack

Category	Tools
Package management	uv
Task automation	taskipy
Linting + formatting	Ruff
Type checking	PyRight
Testing	pytest + Hypothesis
Coverage	pytest-cov (100% required)
Documentation	pdoc + ghp-import
AI development	OpenCode agents + skills

Documentation Site

Published at nullhack.github.io/python-project-template:

• API Reference — pdoc-generated from source docstrings
• Coverage Report — line-by-line coverage breakdown
• Test Results — full pytest run results

Release Versioning

Format: v{major}.{minor}.{YYYYMMDD}

Each release gets a unique adjective-animal name generated from the commit/PR content.

Contributing

git clone https://github.com/nullhack/python-project-template
uv sync --all-extras
uv run task test && uv run task lint

License

MIT — see LICENSE.

---

Author: eol (@nullhack) Documentation: nullhack.github.io/python-project-template