template-engine-copier-3darch/instructions/02-implementation-workflow.md

# Implementation Workflow (Copier + Jinja Template Repository)

Follow this sequence when creating a new template-engine repository.

## Phase 1 — Define rendering contract

1. Define template scope (what downstream repository you generate).
2. Identify stable input schema sections (e.g. tenant/project/environments/resources).
3. Decide what is:
   - static files,
   - conditional files/folders,
   - repeatable per-instance blocks.

Deliverable: first draft of `copier-answers.example.yaml`.

## Phase 2 — Bootstrap Copier skeleton

Create:

- `.copier/copier.yaml`
- `.copier/questionnaire/*.yml`
- `{{ _copier_conf.answers_file }}.jinja`

Use baseline:

- `_template_suffix: ".jinja"`
- modular `!include .copier/questionnaire/*.yml`
- explicit `_exclude` list
- `_answers_file: copier-answers.yml`

## Phase 3 — Create operational wrappers

Implement wrapper chain:

1. root `Taskfile.yml` includes `.scripts/copier/Taskfile.yml`
2. `.scripts/copier/Taskfile.yml` exposes `bootstrap-one`
3. `.scripts/copier/api/bootstrap-one.sh` remains thin
4. **confirm ENV var prefix with user** (or propose one) before implementing lib internals
5. `.scripts/copier/lib/` contains logic and answers merge helpers

Minimum behavior in lib:

- parse CLI args with both styles: `--arg value` and `--arg=value` (for `--copier-target-dir`, `--copier-force-copy`, `--copier-params-file`),
- prepare merged answers file,
- run `copier copy --trust --data-file ...` from a sibling temporary copy of the template repo, not from the live template repo folder,
- post-render sanitization/renames if needed.

Mandatory temp-copy bootstrap pattern from `iac-tmpl-aws-projects`:

- In `api/bootstrap-one.sh`:
  1. derive the live template folder name from `basename "$PWD"`,
  2. delete any old sibling `../tmp-${TEMPLATE_FOLDER}`,
  3. copy the whole template repo into `../tmp-${TEMPLATE_FOLDER}`,
  4. `cd` into the temp folder,
  5. source `.scripts/loggers/lib/--index.sh` and `.scripts/copier/lib/--index.sh`,
  6. execute `_copier_bootstrap_one`,
  7. return to the original live template folder.
- In `lib/-bootstrap-one.sh`, before `copier copy`:
  1. copy `.copier/copier.yaml` to root `copier.yaml` if the repo uses `.copier/copier.yaml`,
  2. remove `.git`, `.devbox`, and `.venv` from the temp copy,
  3. run Copier from the temp folder into the real target.

Do **not** create Git tags merely to silence Copier's local template version warning. The preferred local bootstrap hygiene is rendering from the sanitized temp copy. Use `--vcs-ref=HEAD` only when there is an explicit reason to render directly from a Git-backed live folder.

## Phase 4 — Add Jinja template layers

1. Add top-level templates (`iac/main.tf.jinja`, providers, backend, etc.).
2. Gate directories via folder-name expressions:
   - `{{ 'dev' if flat.dev_is_enabled }}`
3. Gate module calls inside files via `{% if ... %}`.

Pattern:

- folder condition controls existence,
- inner condition controls file content clarity.

**Mandatory wrapped render-path rule:**

- For every optional module/resource, apply conditions at the **path level** (folder/file names), not only inside file contents.
- Preferred pattern (from `iac-tmpl-aws-projects`):
  - `iac/{{ 'dev' if flat.dev_is_enabled }}/{{ 'compute' if flat.dev_compute_is_enabled }}/main.tf.jinja`
- Apply this systematically to all optional Jinja outputs so disabled features do not produce placeholder files/directories.

**Mandatory safe-variable rule:**

- Do not embed repeated normalization/sanitization logic in template paths or file bodies, e.g. avoid:
  - `{{ project.name | lower | replace(' ', '-') | replace('_', '-') | replace('.', '-') }}`
- If a safe name is needed, calculate it once in the context hook and expose a named variable, e.g.:
  - `flat.project_safe`
  - `flat.environment_safe`
  - `flat.component_safe_names`
- Use the named variable in templates:
  - `applications/{{ flat.project_safe }}/main.yaml.jinja`
- If a one-off transformation is genuinely needed, prefer a small deterministic resolver over duplicating filter chains.

## Phase 5 — Add custom extensions (if complexity requires)

When logic gets repetitive, move it into extensions.

### Resolver extension examples

- normalize names: `resolve_safe_tf_module_name(name)`
- derive tags / regions / zones

### Context hook extension examples

- calculate `flat.*` shortcuts,
- calculate safe/normalized names such as `flat.project_safe` and `flat.environment_safe`,
- expand `[INDEX]` directories into per-instance folders.

Register in `.copier/copier.yaml` under `_jinja_extensions`.

## Phase 6 — Implement answers merge strategy

Use this exact order to avoid destructive updates:

1. `copier-answers-new.yml` create if missing,
2. copy `<target>/copier-answers.yml` if present,
3. merge params file into working answers file (`yq eval-all ...`).

Then run copier using merged file.

## Phase 7 — Handle template/self-repo conflicts

If template repo contains files that should not be copied 1:1 (e.g. self CI):

1. render as temp name (`.tmp-gitlab-ci.yml`),
2. rename in target during bootstrap.

## Phase 8 — Add docs and examples

Add/update:

- `README.md` with local setup and bootstrap command,
- `copier-answers.example.yaml` with realistic schema examples,
- optional `bootstrap-one-test` task for local maintainer testing.

## Phase 9 — Validate end-to-end

Run two critical scenarios:

1. fresh render into empty target,
2. re-render into existing target with existing `copier-answers.yml`.

Both must succeed without manual edits.

## Quick-start from this skill example

If you want to accelerate implementation, copy `example/` and then:

1. expand questionnaire files,
2. expand `flat.*` derivation logic in context hook,
3. add domain-specific resolver extensions,
4. extend `iac/**/*.jinja` resource tree,
5. keep bootstrap/answers flow unchanged unless you have a strong reason.