Przejdź do treści
Biblioteka skilli
Programowanie · Przegląd i audyt

template-contract

/template-contract

Opisuje wiążący kontrakt szablonów Copier: pliki, pytania, manifest i zasady wersjonowania potrzebne do copier update.

Repozytorium
wellforge ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Opisuje wiążący kontrakt szablonów Copier: pliki, pytania, manifest i zasady wersjonowania potrzebne do copier update.

Oryginalny opis (EN)

The binding contract every WellForge Copier template must satisfy — the single root copier.yml, the shared question set, required generated files, the manifest, and the versioning rules that make `copier update` work. Use when adding or editing a preset, when writing an org-internal template with $wf-extract-template, when a scaffold or an upgrade behaves unexpectedly, or when deciding which version series a change belongs to. Authoritative reference for the monorepo template pattern, the no-hidden-answers rule, the two independent version series, and what a template may never do.

Jak działa

  1. One copier.yml at the repo root
  2. The shared question set
  3. Required generated files
  4. Two version series, deliberately independent
  5. What a template may never do
Sekcje z nagłówków SKILL.md, w oryginale · 96 linii, 791 słów
Podgląd SKILL.md
---
name: template-contract
description: >
  The binding contract every WellForge Copier template must satisfy — the single root
  copier.yml, the shared question set, required generated files, the manifest, and the
  versioning rules that make `copier update` work. Use when adding or editing a preset,
  when writing an org-internal template with $wf-extract-template, when a scaffold or
  an upgrade behaves unexpectedly, or when deciding which version series a change belongs
  to. Authoritative reference for the monorepo template pattern, the no-hidden-answers rule,
  the two independent version series, and what a template may never do.
---

# Template contract

Every WellForge Copier template must satisfy this. `$wf-new` and
`$wf-upgrade` depend on it, and the lifecycle breaks quietly when a template drifts
from it — usually at `copier update`, months later, in someone else's project.

The canonical copy lives at `templates/_shared/CONTRACT.md` in the wellforge repo; this
skill is what an agent carries into a project that has no access to that file.

## One copier.yml at the repo root

ONE `copier.yml` at the **repo root** serves every preset: a `preset` question selects the
stack, and `_subdirectory: "templates/{{ preset }}/template"` picks the file tree. Presets
do **not** have their own `copier.yml`; preset-specific questions live in the root file,
guarded with `when: "{{ preset == '<name>' }}"`.

This is not organisational taste. `copier update` requires the template source to be the git
repo root, versioned by repo-wide tags — split the config per preset and the upgrade path
goes with it.

```bash
uvx copier copy --trust <repo or URL> <dest> --data preset=<name>
```

Note for anyone testing a template change: copier renders from the **latest tag**, not your
working tree. To exercise an uncommitted edit, copy the repo without `.git` and render from
there, or pass an explicit `--vcs-ref`.

## The shared question set

Every preset asks these, with these names — `$wf-new` fills them and
`$wf-upgrade` re-uses the recorded answers:

`project_name`, `project_slug`, `description`, `ci`, `rigor`, `gates_repo`, `gates_ref`,
`heartbeat`, `heartbeat_cron`. Stack-specific questions are free per preset but **must have
defaults**, so `copier copy --defaults` always produces a valid project — that is what CI
smoke-tests every preset with.

**No hidden copy-time answers.** A question with `when: false` is not persisted to
`.copier-answers.yml`, so an injected value (a generation date is the classic) diverges from
the re-rendered base and conflicts on every future update. Learned the hard way; generation
date lives in git history, where it already was.

## Required generated files

- `.forge/manifest.json` — template, version, answers. **The upgrade contract.** Never
  hand-edit it, and never hand-edit `.copier-answers.yml`; between them they are the only
  record of where a project came from. It also carries a `plugin` object —
  `{version, set_by: new|adopt|upgrade, at}` — recording which **plugin** version last set
  the project up, because the conventions, file formats, trace schema and hooks all move
  with the plugin and nothing else records that. Adopted projects keep the same object in
  `.forge/adoption.json`.

  The `plugin` object is **written by the command after generation, never asked by copier**.
  A persisted answer would replay the scaffold-time version forever (copier re-renders from
  recorded answers, so an upgrade would still claim the old plugin), and a hidden `when:
  false` answer is not persisted at all, which is the conflict trap this repo already hit
  with a generation date. General rule: **a value that depends on when the command ran is
  written after generation; only what the user answered is a copier question.**

  Because the template never emits the key, a `copier update` re-render does not touch those
  lines and should merge cleanly — and `$wf-upgrade` rewrites the object anyway, so
  the field is right afterwards either way.
- `AGENTS.md` (with `CLAUDE.md` importing it) — the project's own conventions, so an agent
  arriving later reads the project rather than guessing.
- `mise.toml` — pinned toolchain plus `install`/`build`/`test`/`lint` tasks. In a monorepo,
  a root task **cannot** depend on a subdirectory task by name; see [`mise`](../mise/SKILL.md) for the
  addressing rule and the pointer-task pattern.
- CI that **calls** the shared gate workflows pinned to a `gates-v*` tag, passing
  `gates-repo` and `gates-ref` explicitly ([`quality-gates`](../quality-gates/SKILL.md)).
- A `specs/` directory, so the spec-driven flow has somewhere to land ([`spec-driven`](../spec-driven/SKILL.md)).

## Two version series, deliberately independent

| Series | What it versions | Where it lives |
|---|---|---|
| `vX.Y.Z` | the **templates** — what `copier update` resolves | repo-wide git tags, presets in lockstep |
| `gates-v*` | the **gate workflows and configs** | separate tags, invisible to copier |
| `2.x.y` | the **plugin** | `plugin.json`, not a tag |

They move at different rates for different reasons, so a template release does not drag a
gates bump into existing projects, and a plugin fix reaches everyone without a scaffold
change. Semver for templates: patch = cosmetic, minor = additive, major = needs
`_migrations`. Bump the `template_version` default in the release commit, and never tag two
series on one commit.

## What a template may never do

- Ship a secret, or a placeholder that looks like one.
- Depend on a tool it does not pin in `mise.toml`.
- Reference a file it does not generate (the shipped presets once called `./mvnw` with no
  wrapper in the tree — every backend task failed at the first run).
- Carry domain code from the project it was extracted from ([`template-extraction`](../template-extraction/SKILL.md) has the
  mandatory scrub).

Wersje

RepozytoriumWynikLicencja
Ta strona · matteocodogno/wellforge100MIT
matteocodogno/wellforge100MIT

Migawka bazy z 13.11.2026 · wersja paczki d60a5607fb7f (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100applying-template-updates
    Prowadzi przez przegląd i rozwiązanie pull requesta z aktualizacją szablonu (tygodniowa gałąź copier/update), także po ręcznym copier update --trust albo gdy aktualizacja nie zostawia miejsca na potrzeby projektu.
  • 100devartslab-project-new
    Tworzy nowy projekt z szablonu copier i podłącza go do konfiguracji workspace'u.
  • 100rseng-project-scaffolding
    Pomaga zaczynać projekty oprogramowania badawczego z utrzymywanych szablonów (Copier, cookiecutter), tworzyć szkielet pakietu Pythona i wciągać aktualizacje szablonu do wygenerowanych projektów.
  • 90template-change
    Zmienia pliki szablonu projektów generowanych, reguły manifestu i wersje pakietów oraz naprawia błędy kontrolne w weryfikacji.
  • 100website-cloning
    Klonuje strony internetowe z dokładnością do piksela w potoku v2.0 z Firecrawl, Design Copier i Playwright: tokeny dla sekcji, stany interaktywne i tryb ciemny.
  • 100sync-mech
    Aktualizuje Mecha do nowszej wersji szablonu mechmaker: pokazuje zmiany z pull requestów, pozwala wybrać te, które wejdą, i scala je z własnymi zmianami.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.