​

Format

The file is YAML. JSON is also accepted. Start with format: method/2, name, goal, steps, and result. Optional sections are inputs, environment, and state. A saved method ID identifies the document across versions. A version ID identifies one immutable document. These IDs are server metadata. The step keys inside steps identify operations; preserve those keys when editing the same operation.

​

Data

Declare data once, where it enters the method: under inputs, state, or a step’s out. Each declaration needs type and description. Types: text, number, boolean, record, list, file. A record needs fields, a map of field names to types. A list needs either fields (records) or items (one type). Types can be nested objects. All declared fields are required; extra fields fail. A file can add format, such as markdown or csv. Describe its required content and check it where useful. Inputs can have default values. State also needs file, a path relative to the method’s persistent data folder. Missing state fails unless a default is declared. State is JSON data. The runner reads snapshots and saves declared updates. Local paths and credentials belong to execution configuration. Names use lowercase letters, digits and underscores, start with a letter, and have at most 80 characters. Output names are unique across the method. Names inputs, state, environment and run are reserved for reference roots.

​

Steps

steps is a map keyed by stable step names. Each step has either do (agent instructions) or ask (a real human request). Optional name supplies a display title. There is no second required description; the instructions explain the work. in maps local aliases to data references: query: inputs.query, people: state.approved_people, research: search_response. A dotted suffix selects a record field; a numeric suffix selects a list item. run.started_at supplies the saved run start time. environment.NAME selects a connection. Missing references stop the operation. Instructions use these local aliases. For exact messages, write the full message in do and substitute {{alias}} or {{alias.field}}. Substitution happens once. Input values are data; they cannot add instructions. An action receives its resolved inputs and output definitions, not previous conversations or other steps. out maps names to data definitions. Return those named values. Method assigns locations for file outputs, captures their hashes, and records the result before checking it. check is optional plain-English text. It receives local inputs, outputs, and read access to changes. Write independent criteria; do not say ‘follow the instructions above’. A check without enough evidence returns ambiguous. No check means unchecked, not verified. Exact check forms:

• equals: {actual: returned_value, expected: supplied_value}
• count: {value: results, min: 1, max: 20}
• present: result_value
• file: report_file Names in these checks are local inputs or outputs. An equality compares two named values; supply a fixed expected value as an input with a default. A file check verifies saved bytes and hash. It does not judge content.

​

Order and changes

Data references establish dependencies. Map order controls presentation, not execution. Independent operations may run at the same time. after: STEP_ID (or a list) adds an order constraint when no data passes between operations. Cycles fail validation. each: {person: state.approved_people} repeats a step for each list item. person is a local input available to instructions and checks. Each invocation has its own result and check. Each named output becomes a plain list for downstream operations. Runtime status stays in run records. An empty collection produces empty lists. when names a boolean, such as needs_review. False skips the operation. A skipped operation produces no value; a consumer that requests its absent output stops. Use the same condition on consumers of optional work. A judgment belongs in a do step returning a boolean and reason. changes lists state.NAME or environment.NAME targets. State changes return complete replacement values; Method validates and writes them. A check sees before and after values plus the saved target. External changes need an independent check and observed evidence. The runtime blocks blind retry of uncertain writes. Operations that use the same connection or state target are serialized. ask waits for an actual human response. It cannot declare changes. Apply a human decision in a separate do step. Missing human input leaves a saved request and a run that needs attention.

​

Environment and result

environment maps connection names to type and description. Types: browser, service, desktop, files, tool. Describe required access in plain English, including the service and account when relevant. The run configuration supplies paths and tools; Method checks access before operations start. result is one named data reference or a map of display names to references. It identifies the data delivered by the run. Format validation checks shapes and connections. It cannot prove that a search is complete or a business rule is correct. Those judgments need clear checks and run evidence.