Spec gap: `template_strings` instantiation syntax and namespace sharing with `templates` are undefined #12

New issue

Open

opened 2026-05-27 05:25:46 +00:00 by hurui200320 · 0 comments

hurui200320 commented

2026-05-27 05:25:46 +00:00

Member

Problem

§8.9 introduces the template_strings section for raw structural templates — templates containing {% for %} loops that generate YAML keys — and states they must be preserved verbatim until instantiation.

However, §8.9 never specifies how to instantiate a template from template_strings. The example in §18.11 uses the same template: <name> syntax as for templates:

agents:
  legal_team:
    template: fanout_team   # <-- is this resolved from `template_strings` or `templates`?
    params:
      team_size: 4
      domain: "contract review"

Neither §8.9 nor §8.7 (Template Instances) address:

Is the resolution namespace shared between templates and template_strings? I.e., can you instantiate a template_strings entry using template: <name>?
What happens if the same name exists in both templates and template_strings? Which takes precedence?
Is the instantiation process for template_strings identical to Phase B for templates, or does it go through a different mechanism (since the body must be text-rendered and then YAML-parsed at instantiation time rather than having expressions rendered into an already-parsed structure)?

Impact on Library Implementation

The template resolution and instantiation pipeline cannot be implemented correctly without knowing whether templates and template_strings share a namespace and how template_strings entries are instantiated. If they are treated identically by the template: key, the library must handle the structural-template case (text → render → parse → merge) differently from the component-template case (parse → render expressions into values).

Fix Needed

In §8.9, add:

An explicit statement that template_strings entries are resolved by the same template: key in agents/routes
The namespace precedence rule if names collide between templates and template_strings
The instantiation pipeline for template_strings entries (text render → YAML parse → merge into parent)

References

§8.7 — Template Instances (does not mention template_strings)
§8.9 — The template_strings Section
§18.11 — template_strings for Structural Templates (uses template: key without stating it resolves from template_strings)

## Problem §8.9 introduces the `template_strings` section for raw structural templates — templates containing `{% for %}` loops that generate YAML keys — and states they must be preserved verbatim until instantiation. However, §8.9 never specifies **how** to instantiate a template from `template_strings`. The example in §18.11 uses the same `template: <name>` syntax as for `templates`: ```yaml agents: legal_team: template: fanout_team # <-- is this resolved from `template_strings` or `templates`? params: team_size: 4 domain: "contract review" ``` Neither §8.9 nor §8.7 (Template Instances) address: 1. Is the resolution namespace shared between `templates` and `template_strings`? I.e., can you instantiate a `template_strings` entry using `template: <name>`? 2. What happens if the same name exists in both `templates` and `template_strings`? Which takes precedence? 3. Is the instantiation process for `template_strings` identical to Phase B for `templates`, or does it go through a different mechanism (since the body must be text-rendered and then YAML-parsed at instantiation time rather than having expressions rendered into an already-parsed structure)? ## Impact on Library Implementation The template resolution and instantiation pipeline cannot be implemented correctly without knowing whether `templates` and `template_strings` share a namespace and how `template_strings` entries are instantiated. If they are treated identically by the `template:` key, the library must handle the structural-template case (text → render → parse → merge) differently from the component-template case (parse → render expressions into values). ## Fix Needed In §8.9, add: 1. An explicit statement that `template_strings` entries are resolved by the same `template:` key in agents/routes 2. The namespace precedence rule if names collide between `templates` and `template_strings` 3. The instantiation pipeline for `template_strings` entries (text render → YAML parse → merge into parent) ## References - §8.7 — Template Instances (does not mention `template_strings`) - §8.9 — The `template_strings` Section - §18.11 — `template_strings` for Structural Templates (uses `template:` key without stating it resolves from `template_strings`)

Rows
Columns

Spec gap: template_strings instantiation syntax and namespace sharing with templates are undefined #12

Problem

Impact on Library Implementation

Fix Needed

References

Spec gap: `template_strings` instantiation syntax and namespace sharing with `templates` are undefined #12