A private template is reusable AI work IR that you create and maintain. Its source definition is a TemplateSpec JSON file, and each change becomes a new immutable version.
Use a private template when an official template does not match your input fields, workflow steps, dependencies, model requirements, or outputs.
Plan before compiling
Describe the intended outcome in business terms, including what one workbook row represents, required inputs, workflow steps, visible intermediate results, final outputs, and failure behavior. Review that TemplatePlan before generating TemplateSpec.
Author safely
Start with the documentation bundled with your installed CLI:
The command syntax is loomloom template-spec docs [topic] --lang en|zh-CN. In addition to the main spec, authoring, and examples entries, focused topics cover metadata, inputs, steps, bindings, and execution units. Omit the topic to print the index; use all to print every bundled topic. English is the default language. The installed modular Agent Skill contains the current conversational authoring protocol, while the conversation topic remains available as a compatibility entry.
Validate the definition locally before creating anything remotely:
Creation changes remote state. Review the template name, purpose, and local check result, then explicitly confirm before creating it.
When the workflow changes, append a version instead of changing historical versions in place:
Topology rule for new authoring
New templates, new versions, and new publication flows must not use bindMode=expanded. The authoring gate rejects it with TS-TOPOLOGY-001.
- Put independently processed dynamic items on separate workbook rows.
- For a fixed number of parallel branches, declare multiple steps.
- Connect fixed steps with
dependsOn and upstreamBindings.
- Do not add invented
parallel or branch properties.
Historical versions that already contain expanded remain readable, precheckable, and executable for compatibility. This does not make expanded valid for new authoring or for switching another historical version into the published position.
Run a fixed version from a workbook
TemplateSpec JSON is the source of truth; a downloaded workbook is derived from one template version. Download a new workbook after changing versions.
For an explicit JSONL integration, upload row data separately, precheck the fixed version, and run only after confirmation:
An input_asset_id references material inside one workflow input. It is not the input_file_id used to supply JSONL rows. Preserve each returned ID exactly and never guess a hidden step ID.
