Repository navigation
Contributing to the Template
The template is a shared dependency of every project. A change here reaches all of them through the weekly update PR, so it's held to a higher bar than a project change.
Search the open and closed issues first. If one matches, add your project's case to it: what you saw, and the workaround you used. Otherwise open one with a form:
-
Template problem: a rendered file, workflow or check that's wrong. It asks for the template version (
_commitin.copier-answers.yml), the language layers and kinds it shows with (every choicecopier.ymloffers; a test keeps them in step), the file, and whether it shows in a fresh render or only aftercopier update. - Feature request: something every project should get.
Blank issues are off. Don't report a security problem in a public issue: contact a maintainer of @metalayerlab/maintainers directly.
- Read the template's
AGENTS.md. Most important: Jinja uses[[ ]]and[% %], so GitHub Actions'${{ }}needs no escaping, and[[may never appear in a.jinjafile except as a variable. - Branch and edit. Language-neutral changes go in
template/(orcopier.yml). Anything specific to one language goes inlayers/<lang>/: a value inlayer.jinja, or a fragment that core filesinclude(see Core and layers). Conditional files are conditional in their names:[% if kind == 'service' %]api.py[% endif %].jinja. The one exception is the core files a brain (language: obsidian) drops: they are listed in_excludeincopier.yml(design records 0015 and 0016). - Render and look at the output:
uvx copier copy --trust --defaults -r HEAD -d project_name=demo -d description=demo . /tmp/demo. Keep-r HEAD: without it Copier renders the latest release tag, not your working tree. - Run
uv run pytest(it needs Node.js >= 24 and npm as well as uv), which renders every variant (Python: service, a minimal service, cli, library;none;obsidian; TypeScript: service, cli, library, web) and runs each one's Definition of done, the wiki checks, the manifest checks and actionlint.uv run pytest -m dockeralso builds each image and probes its health endpoint.--variant <name>runs one variant's tests, and--variant restthe tests that render their own answers or none: Template CI runs one job per variant plusrest, so a test that takes theprojectfixture runs in its variant's job and every other test inrest. A new variant needs its entry in the CI matrix, ortest_template_ci_runs_every_testfails. - Update this wiki (CI checks it with
--strictand markdownlint;AGENTS.mdhas the local commands), and open a PR whose Conventional Commit title describes the effect on projects. Use!for anything that will fail a project's CI after the update (a new required heading, a stricter check, a renamed question). - Release with the template's own Release PR. Projects pick it up at their next update.
With an AI assistant, start from the template's own prompts in docs/ai/prompts.md: triaging a project's report, a design record, a new Copier question, a project-owned file, a bug fix, a workflow change, an AGENTS.md change, the PR body, a review and the checks after a merge.
main is protected by a ruleset: changes arrive only by PR, squash-merged, with every Template CI check, the wiki checks and the PR-title check passing, and an approval from @metalayerlab/maintainers (.github/CODEOWNERS). Organisation admins can merge a PR without the approval, for when the only maintainer is the author, but can't push to main directly.
When deciding whether a file is template-owned or project-owned (_skip_if_exists): make it project-owned only if projects must diverge from it. Project-owned files never receive another fix.
The template's outstanding work is in its root TODO.md, which also lists ideas that were rejected and why. A design record that is Approved but not fully implemented gets a TODO.md line or an issue for what's left, so it is tracked rather than only described.
A project's AGENTS.md is read in every assistant session, so the skeleton may use only 75% of its budget (6,750 of 9,000 characters, tests/test_render.py). A PR that changes template/AGENTS.md.jinja says how many characters it adds or frees, and the category of each cut (design record 0006).
A cut is free when an assistant would do nothing differently without the text. From cheapest to most costly:
- Redundancy: text that repeats what another line already says.
- Anything CI enforces: if it's forgotten, the check fails and its message teaches the rule.
- Reasons for rules that are already intuitive: these can live in the wiki.
- Pointers: without the link, the detail exists but is never found.
- A reason for a counter-intuitive rule: without it, the rule is applied too literally or talked around.
-
Specifics that differ from an assistant's defaults (
uv run,typer.echo, the config precedence): without them, the assistant does what most repositories do. - Triggers: a rule without its "when" gets misapplied.
- Unenforced rules about behaviour (stop for approval, never claim an unrun check passed): only a careful reviewer backs these up.
Compression has a limit too: if a new contributor can't read a line first time, an assistant may misread it silently.
Before a cut in categories 4β8, measure it. Render two projects, one with the longer AGENTS.md and one with the shorter, give an assistant the same task in each, and compare which rules each run follows. When the skeleton reaches 6,750 characters, write a new design record instead of raising the budget piecemeal.
| Change | Edit |
|---|---|
| Something every project gets, whatever the language (a workflow step, the wiki standard, a manifest) | template/ |
| A language's command, tool, image or wording |
layers/<lang>/layer.jinja (a value) or a fragment under layers/<lang>/
|
A whole file only one language has (pyproject.toml, package.json, src/, tests/) |
template/, gated in its name by language
|
Core files read a layer with [% import 'layers/' ~ language ~ '/layer.jinja' as layer with context %], then [[ layer.test ]] and [% include 'layers/' ~ language ~ '/ci/jobs.yml.jinja' %]. The tests/test_layers.py checks fail if language tooling lands in a core file, or if a layer is missing a value or fragment the core uses.
A layer value may be empty (layers/none/ leaves nearly all of them empty). The core then skips the line or row that uses it: guard on the value ([% if layer.gen_wiki %]), never on the language ([% if language == 'none' %]). The other layers' renders must not change when you add a guard or a value: render them before and after, and diff.
Python and TypeScript are the real layers for code; obsidian is the layer for a notes vault, whose only kind is brain. Start from a copy of the closest one and rewrite each value and fragment. The full contract (every layer.* value, every fragment, the gated whole files, questions and test variants) is in the template's layers/README.md, and uv run pytest tests/test_layers.py lists whatever is still missing. Start with a design record in the template's docs/design/.
project-template | The metalayerlab project template
GitHub β’ Releases β’ Changelog β’ Contributing
This wiki is generated from docs/wiki/ on every push to main: edits made here are overwritten. Change it with a pull request.
- π
copier updatekeeps every project in step - π·οΈ release-please: reviewed Release PRs and generated changelogs
- π A standardised, CI-checked wiki in every repo
- π€ One
AGENTS.mdfor Claude, Codex, Copilot, Gemini and Cursor - π³ Hardened Docker, Kubernetes and systemd manifests