python-scaffold
The project's environment, not its architecture: ford lays the architecture
inside a project that already builds and runs its tests.
Before
- The project directory is the current directory, or a new folder that
--dir <folder> creates (a project inside an existing repository); it
holds nothing the templates write (scaffold python PROJECT_NAME=x --dry-run lists them).
- Ask the user (in the workflow, through kent's relay), in one question
each, with the default first, only what kent's prompt and the shopping
list do not already give. A user's delegation of the technology choices
to your recommendations covers these questions too: take the defaults and
report the values you used.
- Project name: the directory's basename. The distribution name.
- Package: the name as a lowercase identifier (
agent-bench →
agent_bench). The import name, under src/.
- Python version:
3.12. The minimum version, requires-python.
- GitHub repository (
owner/name) for the CI badge, or none.
Run
scaffold python PROJECT_NAME=<name> PACKAGE=<package> PYTHON=<version> GITHUB_REPO=<owner/name> [--dir <folder>]
It creates:
pyproject.toml hatchling, dev group: pytest, hypothesis, ruff, mypy
.python-version the Python version uv uses
Makefile deps (Arch, Ubuntu), install, build, test, lint,
format, typecheck, check, clean
src/<package>/ __init__.py, py.typed
tests/test_import.py one test, so the runner has something to run
.github/workflows/ci.yml uv, make install, make check, make test
.gitignore, README.md
toolchain.yaml language: python (see workflow-files for versioning)
then git init and an empty start. commit, unless the directory is inside
a repository already. It refuses to overwrite a file.
With --dir inside a repository, the CI goes to the repository's root
(.github/workflows/<folder>.yml, every step run in the folder, triggered
only by changes to the folder and to that workflow): GitHub
reads workflows only from there.
A toolchain.yaml at the root names the folder (project: <folder>), so
that the toolchain tools find the project from there; kent commits it with
the workflow's files.
Verify
scaffold verify [--dir <folder>] runs make install (it downloads the dependencies: ask the
user first), make build, make check and make test, and reports each.
A missing uv or Python: the user runs make deps (it uses sudo; never
run it yourself). Report failures with their output.
After
- Once verify passes, on the feature branch (
linus refuses master and
main), commit the scaffold: scaffold commit [--dir <folder>] --model <id> commits every untracked file of the project as chore: scaffold the project, the lock file included, and leaves the workflow's files out.
Never hand this commit to the user.
- The tests and the checks run through
toolchain from now on (see the
python-handbook skill).
1---2name: python-scaffold3description: Creates a new Python project with the scaffold tool - src layout, uv, pytest with Hypothesis, ruff, mypy --strict, a Makefile task runner, GitHub Actions CI, git init with an empty "start." commit and toolchain.yaml. ford loads it on a greenfield Python project, before the architecture; the user can also run it on their own.4metadata:5 source: https://skillmd.com/skills/korsmakolnikov/python-scaffold6---78# python-scaffold910The project's environment, not its architecture: ford lays the architecture11inside a project that already builds and runs its tests.1213## Before1415* The project directory is the current directory, or a new folder that16 `--dir <folder>` creates (a project inside an existing repository); it17 holds nothing the templates write (`scaffold python PROJECT_NAME=x18 --dry-run` lists them).19* Ask the user (in the workflow, through kent's relay), in one question20 each, with the default first, only what kent's prompt and the shopping21 list do not already give. A user's delegation of the technology choices22 to your recommendations covers these questions too: take the defaults and23 report the values you used.24 1. **Project name**: the directory's basename. The distribution name.25 2. **Package**: the name as a lowercase identifier (`agent-bench` →26 `agent_bench`). The import name, under `src/`.27 3. **Python version**: `3.12`. The minimum version, `requires-python`.28 4. **GitHub repository** (`owner/name`) for the CI badge, or none.2930## Run3132```sh33scaffold python PROJECT_NAME=<name> PACKAGE=<package> PYTHON=<version> GITHUB_REPO=<owner/name> [--dir <folder>]34```3536It creates:3738```39pyproject.toml hatchling, dev group: pytest, hypothesis, ruff, mypy40.python-version the Python version uv uses41Makefile deps (Arch, Ubuntu), install, build, test, lint,42 format, typecheck, check, clean43src/<package>/ __init__.py, py.typed44tests/test_import.py one test, so the runner has something to run45.github/workflows/ci.yml uv, make install, make check, make test46.gitignore, README.md47toolchain.yaml language: python (see workflow-files for versioning)48```4950then `git init` and an empty `start.` commit, unless the directory is inside51a repository already. It refuses to overwrite a file.52With `--dir` inside a repository, the CI goes to the repository's root53(`.github/workflows/<folder>.yml`, every step run in the folder, triggered54only by changes to the folder and to that workflow): GitHub55reads workflows only from there.56A `toolchain.yaml` at the root names the folder (`project: <folder>`), so57that the toolchain tools find the project from there; kent commits it with58the workflow's files.5960## Verify6162`scaffold verify [--dir <folder>]` runs `make install` (it downloads the dependencies: ask the63user first), `make build`, `make check` and `make test`, and reports each.64A missing `uv` or Python: the user runs `make deps` (it uses `sudo`; never65run it yourself). Report failures with their output.6667## After6869* Once verify passes, on the feature branch (`linus` refuses `master` and70 `main`), commit the scaffold: `scaffold commit [--dir <folder>] --model71 <id>` commits every untracked file of the project as `chore: scaffold the72 project`, the lock file included, and leaves the workflow's files out.73 Never hand this commit to the user.74* The tests and the checks run through `toolchain` from now on (see the75 `python-handbook` skill).