template-engine-copier skill: initial import

Copier + Jinja template-repository design skill: reference architecture, implementation workflow, validation checklist, and a full worked example template (questionnaire, extensions, resolvers, wrapper-first .scripts). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-12 22:30:29 +03:00
commit 97991021ff
29 changed files with 932 additions and 0 deletions
@@ -0,0 +1,120 @@
+---
+name: template-engine-copier
+description: Design and implement a Copier + Jinja based template repository, following the proven patterns used in iac-tmpl-aws-projects and iac-tmpl-aws-organizations.
+---
+
+# template-engine-copier
+
+Use this skill when you need to **create, refactor, or standardize** a repository that acts as a **Copier template engine** for downstream projects.
+
+This skill is based on real patterns from:
+
+- `iac-tmpl-aws-projects/`
+- `iac-tmpl-aws-organizations/`
+
+and is meant to guide creation of repositories that have:
+
+1. clear questionnaire-driven inputs,
+2. deterministic Jinja rendering,
+3. conditional folder/file generation,
+4. safe bootstrapping and re-render workflows.
+
+It now also includes a **concrete scaffold** you can copy from:
+
+- `example/`
+
+---
+
+## Goal
+
+Deliver a template repository where operators can run one command like:
+
+```bash
+task copier:bootstrap-one -- --copier-target-dir "../target-repo" --copier-params-file "./copier-answers.yaml"
+```
+
+and get a rendered repository with predictable structure and preserved answer history.
+
+---
+
+## Read in this order
+
+1. `instructions/01-reference-architecture.md`
+2. `instructions/02-implementation-workflow.md`
+3. `instructions/03-validation-checklist.md`
+4. `example/README.md` and `example/`
+
+---
+
+## Canonical architecture (from analyzed repos)
+
+```text
+<template-repo>/
+  .copier/
+    copier.yaml
+    questionnaire/*.yml
+    extensions/
+      context_hook_extension/    # optional but recommended for complex templates
+      resolvers/
+  .scripts/
+    copier/
+      Taskfile.yml
+      api/bootstrap-one.sh
+      lib/
+        --env-vars-reader.sh
+        --index.sh
+        --index-api.sh
+        -bootstrap-one.sh
+        answers/
+          --index-api.sh
+          -new-ensure-existance.sh
+          -previous-pull-and-merge.sh
+          -params-pull-and-merge.sh
+    base/
+    loggers/
+  Taskfile.yml
+  {{ _copier_conf.answers_file }}.jinja
+  {{ '.tmp-gitlab-ci.yml' }}.jinja
+  src/**/*.jinja
+```
+
+---
+
+## Non-negotiable conventions
+
+1. Keep Copier source-of-truth in `.copier/copier.yaml`.
+2. Keep questions separated under `.copier/questionnaire/*.yml` and include via `!include`.
+3. Use `.jinja` suffix and render both file contents and file/folder names.
+4. For dynamic instance folders, support `[INDEX]` expansion pattern via context hook.
+5. Keep operational entrypoint wrapper-first: `Taskfile -> api -> lib`.
+6. Merge answers in this order:
+   - previous target answers,
+   - explicit params file,
+   - final merged file used for `copier copy --data-file ...`.
+
+---
+
+## Anti-patterns to avoid
+
+1. Putting all logic directly into one giant Jinja file.
+2. Copying templates without answer merge strategy (breaks update flows).
+3. Embedding one-off shell logic directly in Taskfile instead of API/lib wrappers.
+4. Using ad-hoc variable names instead of stable normalized `flat.*` style for complex conditions.
+5. Ignoring render-time safety for generated CI files (e.g., temp naming + controlled rename).
+
+---
+
+## What to copy first (practical)
+
+When building a new template repo, copy these parts first from `example/`:
+
+1. `.copier/copier.yaml`
+2. `.copier/questionnaire/0100-template.yml`
+3. `.copier/extensions/context_hook_extension/hook.py`
+4. `.copier/extensions/resolvers/resolve_safe_identifier.py`
+5. `.scripts/copier/` (all files)
+6. `Taskfile.yml`
+7. `{{ _copier_conf.answers_file }}.jinja`
+8. `{{ '.tmp-gitlab-ci.yml' }}.jinja`
+
+Then adapt `src/**/*.jinja` for your domain-specific resources.