The brief

A brief is a small JSON document that describes the process you want automated. It is the generator's input and the only thing the model receives about your process, apart from the curated context the platform assembles around it. A brief says what the work is. It does not say how to do it: the model decides the steps. The platform checks them.

#The shape

Four fields are required. The generator refuses a brief that is missing any of them.

{
  "description": "Process the invoices in Invoices.xlsx: validate each invoice row, append a Processed row to Results.xlsx for valid invoices and record business failures with their reason.",
  "kind": "excel-invoices",
  "id": "process-invoices",
  "displayName": "Process Invoices (Excel-driven)",
  "inputFile": "Invoices.xlsx",
  "inputSheet": "Invoices",
  "outputFile": "Results.xlsx",
  "outputSheet": "Results"
}

• description is the instruction, in your words. It is what the model is asked to satisfy.
• kind is one of four canonical kinds: excel-web-orders, excel-invoices, excel-web-customers or excel-web-escalations. The kind selects the capability shape and the golden examples the model is shown.
• id must equal the file stem of the automation it will produce. process-invoices becomes automations/process-invoices.automation.ts.
• displayName is what the Studio shows.

The four optional data fields name the workbook and sheets the automation reads and writes. Relative names only: the Robot resolves them against its own data directory.

Two more fields exist for briefs outside the four canonical kinds. shape names the golden set the model is shown (excel, web, excel+web, files, email+files, api+files, converted-artifact or canonical). It grants no capability and changes no gate. targets declares target intents, described below.

Ready-made briefs live in tools/briefs/.

#How a brief becomes code

The model does not write the whole file. It returns a body document: the first line is //#ts-automation-body: ts-scaffold-v1. Each part is introduced by a //#ts-section: <name> marker. The names are imports, module, init, getTransaction, processTransaction, onBusinessException, onSystemException and onEnd. getTransaction and processTransaction are required.

runtime/generator/scaffold.ts composes the rest from the brief: the imports, the defineAutomation({...}) wrapper, the metadata block, the default retry policy, the lifecycle signatures, the hook wiring and the closing. It splices the model's sections in verbatim. A body document that carries the shell itself is refused by name, because the platform does not pay a model twice for bytes it generates. A model that answers with a whole file instead is written through byte-for-byte and the run record says which form it took.

The context the model receives includes the rules, the registered target id list and the closest golden examples. The selection is stated in the context, so a reader can see which exemplars a brief was shown and why.

#Declaring targets

Rather than author locators blind, a brief or artifact may declare intents:

{
  "targets": {
    "domain": "billing",
    "url": "https://app.example.test",
    "intents": {
      "billing.statusSelect": { "role": "combobox", "name": "Account status" }
    }
  }
}

An intent is an ARIA role plus the text a human reads. With binding enabled, each intent is proven against the running page and only proven locators are installed. An intent that cannot be proven refuses the run by name.

#A brief from a recording

The desktop Recorder can produce a brief from a recorded trace: desktop brief <trace.json> [--out <file>] [--json]. Each accepted step becomes a named declaration carrying the prover's locator and the note the operator wrote. A step the prover refused is listed as a refusal with its code, never emitted as a selector.