make a template

what a run template is made of, the file and its header, the nodes and cords inside, where your own templates live, what validation refuses, and how the conductor proposes one for you to save.

a template is the graph a run executes: model nodes, builtins and the cords between them. this guide walks what goes in one and how a new one gets into your library. the docs don't give a full worked example, so this stops at what the pages state.

01the file#

a template is one yaml file with a template: header beside the patch document, which is inline. the file is read strictly: an unknown key is an error, and a file with more than one yaml document is refused. see the template file.

the header has these fields:

• name: lowercase letters, digits and dashes. it must match the file name.
• purpose: one line.
• base: optionally the template this one is a variant of.
• inputs: what a run starts from, each with a name and required.
• roles: roles that presets can play, each a role and the model node that plays it.
• writes: true when the run writes to a workspace.
• closes_ticket: true when the run closes its ticket.
• entry and inlet: the node and message inlet that the run's first envelope goes to.
• terminal: optionally the node whose completed invocation ends the run.

02the nodes and cords#

the patch document is version, nodes and cords. a node is a model node, which runs an agent process, or a builtin, which is deterministic code that smith runs itself. a template may not use a subpatch, because a template is one file. see node kinds and fields.

a cord joins an outlet to an inlet, and its delivery is enqueue or latest and nothing else. a cord that sends work back to an earlier node makes a loop, and the hop cap ends a loop that doesn't converge. see ports and cords.

a model node must declare a profile, and a template without one is refused. the profiles are reason, inspect, work and research. see profiles. the builtins and their config keys are listed under builtins.

03start from a shipped one#

eight templates ship with smith:

• batch
• mock-first
• quick-fix
• research
• research-brief
• ticket-close
• ticket-completion
• write

each one's purpose is on shipped templates, and the node ids of ticket-completion are in order under ticket-completion nodes. the base header field is there for a template that is a variant of another.

04where yours lives#

your own templates live at <library_root>/templates/<name>.yaml. a file with a shipped template's name in that folder is what loads, and the shipped bytes are used only when there's no such file. reset removes your copy so the shipped one loads again. save writes the file only if the template validates, and it's the desk window's save route that does it, not a run and not the conductor. see where templates live.

05what validation refuses#

one validator is used when the library loads, when a template is proposed and when it's saved. among other things it refuses a template when:

• the name isn't lowercase letters, digits and dashes, or the purpose is empty or runs to more than one line;
• an input is unnamed or named twice;
• a model node declares no profile;
• a node is a subpatch;
• a builtin isn't a known one;
• the entry node or its inlet doesn't exist;
• a land node can be reached without passing a human gate first;
• the template closes tickets and lacks the ticket contract.

the whole list is under validation.

06proposing it#

the conductor proposes a template with propose_template. it takes a name, a one-line purpose and the whole template file. the desk validates it and puts a template card in the conversation. the card shows the graph, each node's role, model and profile, what each node can touch, the validator's problems, and a diff against the template it varies. nothing is written until you save it to the library on a valid card. once it's saved, a launch card can carry it. see propose_template and choosing a template.

07where to go next#

templates and nodes and builtins have the full pages.