template-engine-copier-3darch/SKILL.md

name, description

name	description
template-engine-copier	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:

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)

<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.