A private template is a workflow that you create and maintain. Its source definition is a TemplateSpec JSON file, and each published change becomes a new immutable version.
Use a private template when an official template does not match your input fields, workflow steps, or outputs.
Author safely
Start with the documentation bundled with your installed CLI:
The installed modular Agent Skill contains the current conversational authoring protocol. The conversation docs 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.
