Skeleton setup for a repository that uses Python invoke tasks, reusable modules, uv for environment/dependency management, and AI Copilot prompts and instructions. Drop this into any project to get a consistent git workflow, linting, and session logging out of the box.
./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.
pyproject.toml # Dependencies (Python >=3.14), ruff/pylint 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)
modules/
common/ # cli.py, properties.py, route_utils.py, utils.py — shared helpers
repo/ # pull.py, push.py, log.py, squash.py, rebase.py, pr_*.py — git/PR workflow modules
setup/ # properties.py — creates/stamps properties.yml, called by setup.sh/setup.ps1
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
tests/ # check_agents.py — verify .github/prompts/ mirrors are in sync, called by tests.check_agents
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 (debug, repo, ruff, setup, template, tests, upgrade, uv, versioning) plus top-level aliases (fix, test, update)
combos.py # Top-level aliases: fix, test, update
debug.py # debug.env — print cwd + sorted env vars
repo.py # repo.pull, repo.push, repo.log, repo.squash, repo.rebase, repo.pr_diff, repo.pr_notes_save, repo.pr_create, repo.pr_cleanup
ruff.py # ruff.fix, ruff.format
setup.py # setup.properties — creates/stamps properties.yml
template.py # template.pull, template.pull_copy, template.push_diff, template.push_apply, template.push_create_pr
tests.py # tests.actionlint, tests.check_agents, tests.pylint, tests.rufflint, tests.yamllint
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
.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 + 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/
.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
uv run --no-sync invoke # List all available tasks
uv run --no-sync invoke test # Ruff + Pylint + 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.log # Save a session log to logs/
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| 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 |
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) |
| Module | Purpose |
|---|---|
modules/common/ |
CLI helpers, properties.yml config reader, output/utility helpers |
modules/repo/ |
Git workflow and session logging |
modules/setup/ |
Creates/stamps properties.yml, called by setup.sh/setup.ps1 |
modules/template/ |
Sync shared, generic tooling with the parent template repo for /template |
modules/tests/ |
Verify .github/prompts/ is mirrored into .claude/commands/, .claude/skills/, and .clinerules/workflows/ |
modules/versioning/ |
Check pyproject.toml deps and workflow action refs vs. latest releases, update locks; bump the repo's VERSION file for deploys/releases |
See modules/README.md for full details.
Optional, project-specific extensions live under addons/<name>/ and mirror the root layout
(modules/, tasks/, .github/, .claude/). They are not usable from inside
template_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
applyToinstruction globs written for a root-level path (e.g.modules/dawn/**) - Need their
tasks/*.pytask module wired into that repo'stasks/__init__.pyCollectionby hand — nothing here auto-discovers them
They're excluded from ruff/pylint here (pyproject.toml extend-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 |
GitHub Actions runs Ruff, Pylint, yamllint, actionlint, and check_agents on every pull request
targeting development or main via .github/workflows/tests.yml.