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

## 3D Architecture Wizzard Project Adoption

This is the primary project-adopted skill for **3D Architecture Wizzard** (`3darch`).

- Central source: https://gitea.lego-cloud.eu/home-v1-skills-code-agent/template-engine-copier
- Source branch: `test`
- Source commit: `97991021fff9e1f73202a82d29eea496ea0eb7aa`
- Adopted repository: https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/template-engine-copier--3darch
- Application: https://gitea.lego-cloud.eu/corp-v1-3darch/corp-v1-3darch
- Documentation: https://gitea.lego-cloud.eu/corp-v1-3darch/corp-v1-3darch-documentation
- Environment namespace: `CORP_V1_3DARCH_*`
- Global diagram skill: https://gitea.lego-cloud.eu/home-v1-skills-code-agent/diagrams-drawio
- Global glossary skill: https://gitea.lego-cloud.eu/home-v1-skills-code-agent/corp-v1--glossary
- Project automation: none; no scheduler job is authorized.

Project engineering peers:
- `development-branching-strategy--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-branching-strategy--3darch
- `development-gitops-argo-cd--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-gitops-argo-cd--3darch
- `development-monorepo-pnpm--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-monorepo-pnpm--3darch
- `development-scripts--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/development-scripts--3darch
- `devsecops-ci-cd-gitea--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/devsecops-ci-cd-gitea--3darch
- `documentation-docusaurus--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/documentation-docusaurus--3darch
- `template-engine-copier--3darch` — https://gitea.lego-cloud.eu/corp-v1-3darch-skills-code-agent/template-engine-copier--3darch


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.