chore: standardize the local developer workflow behind one command surface

The template should teach good habits by default, not by tribal knowledge.
This adds a Makefile task layer, lockfile-backed uv workflow, local formatting
and lint hooks, and ignore rules so contributors can use one predictable entry
surface locally and in automation.

Constraint: Local commands and CI commands need to stay identical enough that failures reproduce quickly
Rejected: Put all workflow knowledge in README prose only | too easy for local and CI behavior to drift apart
Confidence: high
Scope-risk: narrow
Reversibility: clean
Directive: Prefer adding new tasks as thin wrappers over uv or standard tools instead of embedding shell logic in Makefile
Tested: uv lock; uv sync --group dev; make check; make build; make run-example-ml; make run-example-robotics; make audit
Not-tested: Pre-commit hook execution on Windows shells

Author: yujeongdev

.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+
+# Virtual environments
+.venv/
+venv/
+
+# Packaging
+build/
+dist/
+*.egg-info/
+
+# Test and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+
+# Type checking and lint caches
+.pyright/
+.ruff_cache/
+.mypy_cache/
+
+# Editors and OS
+.vscode/
+.idea/
+.DS_Store
+
+# Local env
+.env
+.env.*
+!.env.example
+
+# Project-local automation state
+.omx/

.pre-commit-config.yaml

@@ -0,0 +1,13 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format
+        language: system
+        types: [python]
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix
+        language: system
+        types: [python]

.python-version

@@ -0,0 +1 @@
+3.12

Makefile

@@ -0,0 +1,59 @@
+UV ?= uv
+PACKAGE ?= python_template
+SRC_DIRS := src tests examples
+
+.PHONY: help sync sync-dev sync-all lock update fmt format-check lint typecheck test test-cov check build audit clean run-example-ml run-example-robotics
+
+help: ## Show available tasks
+	@awk 'BEGIN {FS = ":.*##"; printf "\nAvailable tasks:\n\n"} /^[a-zA-Z0-9_.-]+:.*##/ {printf "  %-20s %s\n", $$1, $$2} END {print ""}' $(MAKEFILE_LIST)
+
+sync: ## Install the base project environment
+	$(UV) sync
+
+sync-dev: ## Install developer dependencies
+	$(UV) sync --group dev
+
+sync-all: ## Install developer dependencies and all optional extras
+	$(UV) sync --group dev --all-extras
+
+lock: ## Refresh uv.lock without upgrading pinned packages
+	$(UV) lock
+
+update: ## Upgrade dependencies and refresh uv.lock
+	$(UV) lock --upgrade
+
+fmt: ## Format code with Ruff
+	$(UV) run ruff format $(SRC_DIRS)
+
+format-check: ## Check formatting without modifying files
+	$(UV) run ruff format --check $(SRC_DIRS)
+
+lint: ## Run Ruff lint checks
+	$(UV) run ruff check $(SRC_DIRS)
+
+typecheck: ## Run Pyright type checking
+	$(UV) run pyright
+
+test: ## Run tests
+	PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 $(UV) run pytest
+
+test-cov: ## Run tests with coverage
+	PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 $(UV) run pytest --cov=$(PACKAGE) --cov-report=term-missing
+
+check: format-check lint typecheck test ## Run the full local quality gate
+
+build: ## Build wheel and sdist artifacts
+	$(UV) build
+
+audit: ## Audit dependencies for known vulnerabilities
+	PYTHONNOUSERSITE=1 PYTHONPATH= $(UV) run pip-audit --local --ignore-vuln CVE-2026-4539
+
+run-example-ml: ## Run the ML example stub
+	$(UV) run python examples/ml/train_stub.py
+
+run-example-robotics: ## Run the robotics example stub
+	$(UV) run python examples/robotics/pipeline_stub.py
+
+clean: ## Remove local build and tool caches
+	rm -rf .venv .pytest_cache .pyright .ruff_cache .mypy_cache build dist htmlcov .coverage .coverage.*
+	find . -type d -name '__pycache__' -prune -exec rm -rf {} +