| name | render-gate |
| auto-activate | false |
| description | TDD rendering gate for Copier template development. Writes E2E assertions first, then iteratively fixes the template until all flavors render cleanly. Never commits on a red suite. Use when editing Copier template files (copier.yml, .jinja files, flavor overlays). NOT for non-template projects, runtime code changes, or general testing (use /validate).
|
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:
- Every flavor renders — each combination of Copier choices produces output
- Answers file is valid —
.copier-answers.yml exists and contains expected keys
- Choices mappings are correct — conditional includes/excludes match the choices
- YAML scalars are well-formed — no unquoted colons, no broken folded scalars
- 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:
- Read the error output
- Identify the root cause in the template source
- Fix the template file
- Re-run the full suite (not just the failing test)
- 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
| Symptom | Likely Cause |
|---|
copier copy fails with "not a git repo" | Need --vcs-ref HEAD; template must be committed |
| YAML parse error in rendered output | Unquoted colon in a Jinja variable or description field |
| Missing file in rendered output | Conditional include/exclude doesn't match the flavor choices |
.copier-answers.yml missing keys | New question added to copier.yml without a default |
Jinja UndefinedError | Variable name mismatch between copier.yml and template |
