Template AI Python

Skeleton setup for a repository that uses Python invoke tasks, reusable modules, uv for environment/dependency management, and AI Copilot prompts and instructions. Forks template_python and adds the AI-agent layer on top. Drop this into any project to get a consistent git workflow and linting out of the box.

Setup

./setup.sh # macOS/Linux
.\setup.ps1 # Windows (PowerShell)

Creates a .venv with uv and installs dependencies. Update properties.yml with the local repo path before running tasks.

Project Structure

pyproject.toml # Dependencies (Python >=3.14), ruff/pylint/pytest config
invoke.yml # Invoke config (auto_dash_names: false)
setup.sh # Shell-based setup script (uv venv + uv sync)
properties.yml # Project configuration (repo path/remote, template path/remote)
template.ignore.yml # Paths /template pull/push must never touch (.gitignore handles the rest via git ls-files)
tests/ # One marker-named subfolder per concern (pass scope=<marker> to tests.pytest for a subset)
agents/ # test_check_agents.py — verify .github/prompts/ mirrors are in sync, called by tests.check_agents
drift/
docs/ # test_changelogs_current.py — docs/change_logs/ vs properties.yml, gate for tests.pytest
setup/ # test_setup_properties.py — modules/setup/ (properties.yml bootstrap)
style/ # test_markdown_style.py — Markdown/doc style checks
modules/
common/ # cli.py, properties.py, prompt_commands.py, route_utils.py, utils.py — shared helpers
docs/ # update.py, lib/change_logs.py — changelog sync (docs/change_logs/ vs properties.yml)
hermes/ # sync.py — syncs ~/.hermes/ config + SKILL.md from .github/prompts/
ollama/ # install.py, list.py, status.py, uninstall.py, update.py, helpers.py — local-LLM management
opencode/ # sync.py — syncs .opencode/command/ from .github/prompts/
repo/ # pull.py, push.py, squash.py, rebase.py, pr_*.py — git/PR workflow modules
setup/ # properties.py — creates properties.yml (no-op if it exists), called by setup.sh/setup.ps1; templates/properties/*.yml — tier fragments
template/ # ignore.py, naming.py, pull.py, push.py, resolve.py, route.py, scope.py — sync shared tooling with the parent template repo for /template
versioning/ # libs.py, python.py, workflows.py, upgrade.py, project.py — check pyproject.toml deps & workflow action refs vs. latest releases, bump the repo's VERSION file
tasks/
__init__.py # Wires the invoke Collection: common/ and tests/ (registered at their original top-level names), ai/ (registered at docs, hermes, ollama, opencode, repo, template — tooling downstream repos use to operate on themselves or a specific AI tool), plus the ai.sync combo task
ai/
docs.py # docs.update_changelogs
hermes.py # hermes.sync
ollama.py # ollama.install/list/update/uninstall/start/stop/status/restart/clean
opencode.py # opencode.sync
repo.py # repo.pull, repo.push, repo.squash, repo.rebase, repo.pr_diff, repo.pr_notes_save, repo.pr_create, repo.pr_cleanup
template.py # template.pull, template.pull_copy, template.push_diff, template.push_apply, template.push_create_pr
common/
main.py # Top-level aliases: fix, test, update, plus ai_sync (was combos.py)
debug.py # debug.env — print cwd + sorted env vars
ruff.py # ruff.fix, ruff.format
setup.py # setup.properties — creates/stamps properties.yml
upgrade.py # upgrade (default), upgrade.python, upgrade.libs, upgrade.sync — installs; run ver.update first
uv.py # uv.upgrade_bin, uv.upgrade_libs
versioning.py # ver.libs, ver.python, ver.workflows, ver.all, ver.update, ver.upgrade, ver.project_bump_build, ver.project_bump_release
tests/ # One file per check (actionlint.py, check_agents.py, pylint.py, pytest.py, rufflint.py, yamllint.py) — still one flat tests.* namespace
.github/
instructions/ # Copilot instruction files
prompts/ # /push, /pull, /squash, /rebase, /fix, /test, /docs, /pr-notes, /pr, /pr-cleanup, /ship-it, /template, /update, /upgrade, /repo, /setup — source of truth
skills/ # Optional GitHub Copilot skills (SKILL.md), not a required mirror of every prompt
workflows/
tests.yml # CI: ruff + pylint + pytest + yamllint + actionlint + check_agents, on PRs to development/main
.claude/
commands/ # Claude Code slash commands, hand-maintained mirror of .github/prompts/
skills/ # Claude Code skills (auto-discovered), hand-maintained mirror of .github/prompts/
.clinerules/
workflows/ # Cline slash commands, hand-maintained mirror of .github/prompts/
.opencode/
command/ # OpenCode slash commands, generated mirror of .github/prompts/ — regenerate via `invoke opencode.sync`, never hand-edit
.vscode/
extensions.json # Recommended VS Code extensions
settings.json # Ruff formatter + Python interpreter settings
addons/
shopfiy_dawn_theme/ # Shopify Dawn theme addon — see Addons below before using

Invoke Tasks

uv run --no-sync invoke # List all available tasks
uv run --no-sync invoke test# Ruff + Pylint + pytest + yamllint + actionlint + check_agents
uv run --no-sync invoke fix # Ruff autocorrect + format
uv run --no-sync invoke update # Run every version check (libs, python, workflows) — top-level alias for ver.update
uv run --no-sync invoke repo.pull # Pull from git remote (stash → pull --rebase → restore)
uv run --no-sync invoke repo.push # Push to git remote (fix → test → commit → push)
uv run --no-sync invoke repo.squash # Anchored squash all commits to root + optional force push
uv run --no-sync invoke repo.rebase # Rebase onto remote default branch (optionally squash first)
uv run --no-sync invoke repo.pr_diff # Print current branch's commit log/diff vs. its base branch
uv run --no-sync invoke repo.pr_notes_save # Save PR notes to tmp/pull_requests/ (--content=...)
uv run --no-sync invoke repo.pr_create # Open a GitHub PR via gh (--title=... --content=...)
uv run --no-sync invoke repo.pr_cleanup # Switch to the default branch, pull, and delete the merged local feature branch
uv run --no-sync invoke template.pull # Resolve the parent template repo's local path for /template
uv run --no-sync invoke template.pull_copy # Clobber-copy tracked files from a local template repo into this project
uv run --no-sync invoke template.push_diff # Diff this repo's scoped tooling against the parent template repo
uv run --no-sync invoke template.push_apply # Copy approved files/deletions to a new branch upstream and push it
uv run --no-sync invoke template.push_create_pr # Open a PR for that branch against the parent template repo
uv run --no-sync invoke ver.libs # Check pyproject.toml deps vs. latest releases, update version locks
uv run --no-sync invoke ver.python # Check the pinned Python version vs. latest stable, update config refs
uv run --no-sync invoke ver.workflows # Check .github/workflows/ action refs vs. latest majors, update pins
uv run --no-sync invoke ver.update # Run every version check (libs, python, workflows)
uv run --no-sync invoke ver.upgrade # Install the Python/library upgrades reviewed via ver.update
uv run --no-sync invoke ver.project_bump_build # Dev build: new minor's first VERSION build, or next build number
uv run --no-sync invoke ver.project_bump_release # Release: drop the VERSION build suffix
uv run --no-sync invoke upgrade # Upgrade Python + all dependencies (default)
uv run --no-sync invoke upgrade.python # Upgrade Python only (installs, rebuilds .venv)
uv run --no-sync invoke upgrade.libs # Upgrade libraries only (uv sync --upgrade)
uv run --no-sync invoke upgrade.sync # Sync dependencies without checking for updates first
uv run --no-sync invoke uv.upgrade_bin # Upgrade the uv binary itself (brew upgrade uv)
uv run --no-sync invoke uv.upgrade_libs # Install the versions currently locked in pyproject.toml (uv sync)
uv run --no-sync invoke setup.properties # Create/stamp properties.yml
uv run --no-sync invoke ai.sync # Sync all AI tool commands from .github/prompts/ (hermes + opencode)
uv run --no-sync invoke hermes.sync # Sync ~/.hermes/ config + SKILL.md
uv run --no-sync invoke opencode.sync # Sync .opencode/command/
uv run --no-sync invoke docs.update_changelogs # Prepend any missing docs/change_logs/ entries from properties.yml
uv run --no-sync invoke ollama.install # Install Ollama + a local coding LLM

AI Prompts

Prompt	Command	Description
/push	uv run --no-sync invoke repo.push	Fix, test, commit, and push to git
/pull	uv run --no-sync invoke repo.pull	Stash, pull latest, restore stash
/squash	uv run --no-sync invoke repo.squash	Anchored squash all commits to root
/rebase	uv run --no-sync invoke repo.rebase	Rebase onto remote default branch
/fix	uv run --no-sync invoke fix	Auto-fix Python linting issues
/test	uv run --no-sync invoke fix && uv run --no-sync invoke test	Auto-fix, then run all tests and linters
/setup	./setup.sh	Run initial project setup
/docs	uv run --no-sync invoke repo.pr_diff && uv run --no-sync invoke docs.update_changelogs	Audit docs and AI-config for drift against recent changes and fix anything stale
/pr-notes	uv run --no-sync invoke repo.pr_diff	Draft PR notes vs. base branch; saves to tmp/pull_requests/ when run standalone
/pr	uv run --no-sync invoke repo.pr_create	Draft PR notes and open a Pull Request via gh (does not push)
/pr-cleanup	uv run --no-sync invoke repo.pr_cleanup	Switch to the default branch, pull, and delete the merged local feature branch
/ship-it	—	Test, audit docs, push, then draft notes and open a Pull Request
/template	uv run --no-sync python -m modules.template.route	Pull shared tooling updates from the parent template repo into this project (or push new generic tooling upstream as a PR)
/update	uv run --no-sync invoke ver.update --dry-run	Check pyproject.toml deps, pinned Python version, and workflow action refs vs. latest releases; update version locks
/upgrade	uv run --no-sync invoke upgrade	Upgrade Python and/or dependencies
/repo	—	Repo operations (push, pull)

Modules

Module	Purpose
modules/common/	CLI helpers, properties.yml config reader, .github/prompts/ parser, output/utility helpers
modules/docs/	Changelog sync — keeps docs/change_logs/<category>/<name>.md in sync with properties.yml
modules/hermes/	Syncs ~/.hermes/ config + SKILL.md from .github/prompts/
modules/ollama/	Local-LLM install/list/status/uninstall/update
modules/opencode/	Syncs .opencode/command/ from .github/prompts/
modules/repo/	Git workflow (pull, push, squash, rebase, PR)
modules/setup/	Creates properties.yml (no-op if it exists) from tier fragments, called by setup.sh/setup.ps1
modules/template/	Sync shared, generic tooling with the parent template repo for /template
modules/versioning/	Check pyproject.toml deps and workflow action refs vs. latest releases, update locks; bump the repo's VERSION file for deploys/releases

tests/agents/test_check_agents.py (not a modules/ package) verifies .github/prompts/ is mirrored into .claude/commands/, .claude/skills/, .clinerules/workflows/, and .opencode/command/ — run via uv run --no-sync invoke tests.check_agents.

See modules/README.md for full details.

Addons

Optional, project-specific extensions live under addons/<name>/ and mirror the root layout (modules/, tasks/, .github/, .claude/). They are not usable from inside template_ai_python — they only work once their files are copied into the consuming repo's actual root, merged with what's already there, because they:

• Import via root-relative paths (e.g. from modules.dawn import list)
• Have applyTo instruction globs written for a root-level path (e.g. modules/dawn/**)
• Need their tasks/*.py task module wired into that repo's tasks/__init__.pyCollection by hand — nothing here auto-discovers them

They're excluded from ruff/pylint here (pyproject.tomlextend-exclude/ignore-paths) since they aren't meant to lint clean from this repo's root.

Addon	Adds	Move these files to the consuming repo's root
addons/shopfiy_dawn_theme/	dawn.list / dawn.upgrade invoke tasks for tracking and staging upstream Shopify/dawn theme upgrades	modules/dawn/ (__init__.py, list.py, upgrade.py, README.md), tasks/dawn.py, .github/workflows/{deploy,promote,release,tests,upgrade}.yml, .github/instructions/dawn.instructions.md, .github/prompts/dawn.prompt.md, .claude/commands/dawn.md

CI

GitHub Actions runs Ruff, Pylint, pytest, yamllint, actionlint, and check_agents on every pull request targeting development or main via .github/workflows/tests.yml.