Render Gate

Render Gate: TDD Template Rendering

A test-driven development loop for Copier template work. The agent writes rendering assertions first, then iterates until every flavor passes.

When to Use

• Editing copier.yml, *.jinja files, or flavor overlays
• Adding a new Copier question or choice
• Modifying the _subdirectory, _tasks, or _templates_suffix config
• After any change that could affect how the template renders

When NOT to Use

• Non-template projects → use /validate
• Runtime code changes that don't affect template rendering
• Documentation-only edits

Procedure

Step 1: Establish the test baseline

Check if bin/verify-template.sh exists and what it covers:

[ -x bin/verify-template.sh ] && echo "verify-template.sh exists" || echo "no verify script"
cat bin/verify-template.sh 2>/dev/null | head -30

Step 2: Write or extend E2E assertions

If bin/verify-template.sh exists, use it as the base. If it doesn't cover the current change, extend it. The assertions must verify:

1. Every flavor renders — each combination of Copier choices produces output
2. Answers file is valid — .copier-answers.yml exists and contains expected keys
3. Choices mappings are correct — conditional includes/excludes match the choices
4. YAML scalars are well-formed — no unquoted colons, no broken folded scalars
5. Jinja syntax is valid — no unclosed tags, no undefined variables

Render from committed git state (not working tree) to match Copier's behavior:

TMPDIR=$(mktemp -d)
uvx copier copy --trust --vcs-ref HEAD --defaults . "$TMPDIR/test-default" 2>&1
echo "Exit code: $?"
ls -la "$TMPDIR/test-default/"

Step 3: Run the full suite and record failures

bin/verify-template.sh 2>&1
echo "Exit code: $?"

Step 4: Iterative fix loop

For each failure:

1. Read the error output
2. Identify the root cause in the template source
3. Fix the template file
4. Re-run the full suite (not just the failing test)
5. Report: what failed, what you fixed, current pass/fail status

Hard rule: Never commit while any test is failing. The loop continues until exit code 0.

Step 5: Final verification

After all tests pass:

bin/verify-template.sh 2>&1
echo "Final exit code: $?"

Only proceed to commit if exit code is 0. Report the full pass summary.

Common Failure Patterns