Python template to quickstart any project with production-ready workflow, quality tooling, and AI-assisted development.
# 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 runA 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 | Discovery + Gherkin stories + @id criteria |
| 2. ARCH | Developer | Design module structure, get PO approval |
| 3. TEST FIRST | Developer | Sync stubs, write failing tests mapped to @id |
| 4. IMPLEMENT | Developer | Red→Green→Refactor, commit per green test |
| 5. VERIFY | Reviewer | Run all commands, code review, @id traceability |
| 6. ACCEPT | Product Owner | Demo, validate, move folder to completed/ |
@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/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 # redirects to verify (quick reference)
/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 systemuv 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 gen-id # Generate an 8-char hex ID for @id tags
uv run task gen-tests # Sync test stubs from .feature files
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| 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 |
@pytest.mark.unit
def test_bounce_physics_a3f2b1c4() -> None:
"""
Given: A ball moving upward reaches y=0
When: The physics engine processes the next frame
Then: The ball velocity y-component becomes positive
"""
# Given
...
# When
...
# Then
...Markers: @pytest.mark.unit · @pytest.mark.integration · @pytest.mark.slow · @pytest.mark.deprecated
| 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 |
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
Format: v{major}.{minor}.{YYYYMMDD}
Each release gets a unique adjective-animal name generated from the commit/PR content.
git clone https://github.com/nullhack/python-project-template
uv sync --all-extras
uv run task test && uv run task lintMIT — see LICENSE.
Author: eol (@nullhack) Documentation: nullhack.github.io/python-project-template