146 lines
5.2 KiB
Markdown
146 lines
5.2 KiB
Markdown
---
|
|
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.
|