forge-template

A Copier template and public composition engine for modern Python projects. The engine catalogue offers independent library and CLI Application archetypes; the compatibility-preserving direct-Copier path remains Library-only and supports copier update through three-way merges.

Quick start

The easiest way to use this template is via its companion CLI, create-forge:

uvx create-forge

You can also scaffold directly with Copier, without the CLI:

uvx copier copy gh:Sandsy09/forge-template your-project --trust

--trust is required — the scaffold runs a _tasks step (git init, first commit) after copying files.

The public engine used by create-forge --engine-preview is also installable directly — pip install forge-template or uv add forge-template — for clients that consume docs/template-engine-api.md's typed discovery/validation/rendering API without going through Copier or create-forge at all. The published wheel ships the engine facade and its Foundation/component content only; this repository's own tooling (docs/adr/ checks, copier.yml/template/ inspection) is not part of the installable package — see ADR 0036.

Two repos

They're kept separate because Copier resolves template versions from PEP 440 git tags on this repo — merging the two would tangle the CLI's own releases with the template's.

What you get

Answer a handful of questions (project name, build backend, license, Python versions to support, ...) and the scaffold gives you a src/-layout package with pyproject.toml (uv or Hatchling), ruff, mypy and/or pyright, pytest with coverage, a poe-driven task runner, pre-commit hooks, GitHub Actions CI, and optional docs (MkDocs) and changelog generation (git-cliff). The question schema in copier.yml is the source of truth for exactly what's asked and what each answer controls.

Layout

forge-template/
├── copier.yml               Question schema for the scaffold
├── pyproject.toml           This repo's OWN tooling (not part of the scaffold)
├── src/, tests/              ^ same
├── docs/adr/                 Why this repo is shaped the way it is
├── scripts/                 verify-ci.sh: push scaffolded combos, watch CI
├── .github/workflows/       This repo's own CI + release automation
└── template/                Everything here becomes the generated project

Contributing

See CONTRIBUTING.md for the human workflow and CLAUDE.md for the invariants that keep copier update working across projects generated at different points in this template's history; read the latter before changing anything under template/. The canonical Forge vocabulary defines architectural terms, the Foundation guarantees define the mandatory outcomes every generated project receives, the Foundation scope defines which concerns belong in that baseline, the Library archetype contract defines the distributable-package additions composed over it, and the CLI Application archetype contract defines the implemented executable reference shape. The composition architecture review records the Stage 08 boundary corrections proven by both archetypes, and the Python support policy defines the supported CPython window and lifecycle, the editor integration strategy keeps the baseline and default profile editor-neutral, the configuration ownership conventions keep runtime settings owner-local and explicitly injected, the environment-variable conventions define owner-prefixed runtime inputs and explicit local dotenv behaviour, the structured logging capability defines owner-local events and one entrypoint-owned logging configuration, the path and resource ownership conventions keep runtime path and resource access owner-local and free of implicit process context, the exception ownership conventions keep exceptions owner-local and require failures to be handled once rather than silently dropped or logged repeatedly, the secret-handling safeguards keep secret-bearing files out of version control without generating a mandatory scanner, the supply-chain provenance contract defines desired SBOM and release-provenance behaviour without generating either yet, the GitHub Action pinning policy keeps remote workflow dependencies immutable and maintainable, the ProjectSpec protocol defines the strict, serialisable generation request for the composition engine, the component manifest protocol defines strict bundled metadata and compatibility for its component catalogue, the composition order contract defines the deterministic order that catalogue applies in, the file conflict and override rules define its output target, disposition, and collision-safety rules, the template variable contract defines the rendered variable namespace and component option vocabulary, the stable template-engine API exposes typed, side-effect-free discovery, validation, planning, and in-memory rendering, the generated-project validation contract checks every rendered result before a client receives it, and docs/adr/ records why significant decisions were made.

License

MIT — see LICENSE.