PROCESS.md

What a PROCESS.md is

Picture: a workflow page on its Workflow tab, with the access line, the PROCESS.md dropdown that lists the files, and the file rendered section by section: Role, Instructions, Rules and Todos.

A PROCESS.md is a business process written down in plain language, in a fixed structure the Ask agent can execute. It is the file behind every workflow. You describe the work the way you would explain it to a colleague, who the Ask agent acts as, what it must do, what it must never do, and where it needs your approval, and the Ask agent executes it end to end across the tools you have connected as sources.

Unlike a flowchart, where every step has to be predefined, a PROCESS.md leaves the judgement to the Ask agent. It adapts to what it finds, handles the cases you did not think of, and pauses for your approval when the file says so. To learn how this differs from a fixed sequence of steps in a tool like Zapier or n8n, read What is agentic workflow automation on the blog.

The structure

Every PROCESS.md follows the same format. A YAML header with the name and description, between two --- lines at the very top, followed by six sections: ## Role, ## Instructions, ## Events, ## Rules, ## Todos and ## Paths. Beside the file, the workflow can carry complementary files called assets, which the Ask agent uses to execute the workflow properly.

Only the header is required. Every other section is optional, but the file has to give the Ask agent enough information to execute the work. Each section you add makes the file more prescriptive: it narrows what the Ask agent decides for itself and fixes what it must do. If there are no todos, the Ask agent works out the steps needed to deliver the description, following the Role and Instructions and obeying the Rules. If the file does not give it enough to go on, it does not guess: the session stops and the Ask agent asks you what to do. A file that does not follow the format exactly is still executed if its purpose and actions are clear: the Ask agent sorts its content into the same sections for itself, without changing the file.

---
name: process-slug
description: What the process does.
---

## Role
## Instructions
## Events
## Rules
## Todos
## Paths

Example: the skeleton of a PROCESS.md, the header and the six section headings, with nothing filled in yet.

The header

Two fields, both required.

---
name: new-client-onboarding
description: >
  Onboard a new client, from contract signature through their first kickoff call and system setup.
---

Example: a header for a client onboarding process, with a description that spans several lines.

Role

The Role says who the Ask agent acts as, who it serves, and whether the process faces your own team or someone outside it. Put it under ## Role, or describe it inside ## Instructions. Either way it applies to the whole process. Without a Role, the Ask agent behaves as an internal assistant to your team.

You do not have to label a Role internal or external. The Ask agent works it out from the purpose and the audience.

• Internal. The Ask agent supports your team or works your internal systems. One outbound task, such as sending an email on a colleague’s behalf, does not make the Role external.
• External. The Ask agent is the one talking to a customer, a lead, an applicant, a supplier or anyone else outside your team. Make the audience clear. If it stays unclear after the whole file is read, the Ask agent stops and asks you for input before it communicates or acts.

An external Role changes how the Ask agent behaves.

• It speaks as the identity the Role gives it, never as Ask or as an assistant of your team.
• It answers and acts only from the conversation, the PROCESS.md with its assets, and verified data from your sources. When it cannot confirm something from those, it never guesses: it follows what the file says to do in that case, and if the file says nothing, it tells the outside party that it cannot confirm it.
• It does only what the Role is for. It does not book, change a record or take any other action unless the file requires it, and it never tells the outside party that something was done unless the source confirms it.
• Nothing internal, an approval, a tool, an error, is communicated to the outside party.

A path inherits the Role, and so does a nested process that has no Role of its own. When a nested process finishes, the Ask agent returns to the parent Role.

## Role
Act as the customer support representative for Acme Homes, speaking directly with tenants about their open repair requests. Be warm, clear, and concise. Answer only from the conversation, this process and its referenced assets, or verified source data. If you cannot confirm something, say so and follow the handoff instructions. Do not book, change, or cancel repairs unless the process explicitly requires it.

Example: an external Role, the Ask agent speaking to tenants as the support representative of Acme Homes, with the limits it must keep.

Instructions

Instructions tell the Ask agent how the whole process must be carried out: the context it needs, what a good result looks like, what it must do and must not do, how to handle the edge cases, and which sources, assets, approvals, output formats or paths apply to the whole process.

They apply everywhere: from the first step to the last, on every run, inside every path, and whenever the session resumes. If the file has todos, the Ask agent keeps their order and titles unless an Instruction or a Rule says otherwise. If it has none, the Instructions are what the Ask agent creates the todos from, as How the Ask agent turns the PROCESS.md into tasks explains. Instructions can change how the rest of the file is executed, but they never let the Ask agent invent work the file does not ask for.

## Instructions
This process applies only to repairs reported by tenants. Use iamproperty for repair history and the Outlook source for contractor messages. Read assets/contractor-tone.md before drafting any message. Contractors are often slow to reply in the first week, so do not treat silence as a refusal. Get approval before sending any outbound message. If the contractor confirms a date, run path tenant-update. Keep the final summary to the outcome and next action.

Example: Instructions for a contractor chase, naming the sources to use, an asset to read first, an approval and a path to run.

Events

The tools you connect as sources publish events, for example a WhatsApp message arrives, a payment succeeds, a document is uploaded or a deal moves stage. This section is where the process subscribes to the events it should listen for. A subscribed event resumes a session that is already open, so a reply is picked up the moment it lands instead of on the next scheduled run, and the Ask agent receives the whole event with all its details, so it knows exactly what happened. The Continuing a session automatically page explains how webhook events continue a session.

If you know the source and the event, write them, one line per event. Filters are optional. Add them to narrow which events get through, or leave them out to receive every one.

## Events
- ai-number / message.received
  where contact_phone is "+447700900123"

Example: an Events section that subscribes the session to WhatsApp messages from one phone number.

Describing how to subscribe to events

You can also describe the event instead of naming it, for example “subscribe to incoming WhatsApp messages from +447700900123”. The Ask agent then uses its Event subscriptions tool to look up the events the source offers, with their filter fields and values, subscribes to the one that matches and tells you which it chose. If none of them matches what you described, it does not settle for a similar one, because a wrong subscription is worse than none. It still executes the todos that do not need the event, and when it reaches the first todo that does, for example one that waits for the customer’s reply, it stops and asks you how to proceed. Naming the exact event, message.received for example, is always the most reliable way. You find the event ids on the source’s Webhook events tab, as Integration sources explains.

Acting as a support or sales agent

Events are also how a workflow makes the Ask agent behave like a support or a sales agent that answers every message as it comes in. Subscribe the session to the incoming messages of the source, without a filter on the sender if it should answer everyone, and give it a Role and Instructions for how to answer. The Ask agent sets the subscription up before it starts the first todo, so it is in place from the start of the session, and from then on every message resumes the session and gets its answer. No auto-run is needed. If each conversation should be its own session instead, set the workflow’s trigger to the message event, and a new session opens for every message.

---
name: whatsapp-repairs-support
description: Answer tenants' questions about their open repairs on WhatsApp.
---

## Role
Act as the customer support representative for Acme Homes, speaking directly with tenants on WhatsApp.

## Instructions
Answer from the tenant's repair record in iamproperty and from assets/repairs-faq.md. If a question is not covered there, tell the tenant a colleague will follow up and run path hand-over.

## Events
- ai-number / message.received

## Rules
Escalate: If a tenant reports an emergency, email the property manager at pm@acme.co.

## Paths

### hand-over
[ ] Email the repairs team
Description: Use the Outlook source to send the tenant's question and the repair reference to repairs@acme.co.

Example: a complete file for a WhatsApp support agent, with a Role, Instructions, an Events line for every incoming message, an Escalate rule and a hand-over path.

Rules

Rules are the conditions, policies and guardrails that apply to the whole process. They rank highest in the file: whenever a Rule overlaps with the Role, the Instructions, the Todos, the Paths, the Events or the description, the Rule wins. The Ask agent checks them before, during and after every todo. Each rule is a label, a colon and the instruction. Two labels are predefined, and you can add your own.

Escalations

By default, an escalation goes to you, the Askpilot user the workflow runs for: the session stops and the Ask agent asks you for input on what to do. You can define any other escalation with the sources the workflow has, for example “email me with the Outlook source” or “message the branch manager on WhatsApp”, and the Ask agent escalates exactly as you wrote it, without stopping the work. An escalation to someone other than you goes by email only for now.

Contact details for escalations

Whenever an escalation names someone, add their email address, phone number or whatever the source needs, so the Ask agent knows where to reach them. A name alone is enough only for a member of your organization, whose details the Ask agent already has.

## Rules
Stop: If the contractor confirmed a date.
Escalate: If a customer complains about product quality, email the product manager at alex.chen@acme.co with the Outlook source.
Language: Always use British English.
CC policy: CC the manager on every dispute email. Manager email: sarah.walker@acme.co

Example: a Rules section with a Stop rule, an Escalate rule to a named person through the Outlook source, and two rules of your own.

Todos

Todos are the steps of the process, which the Ask agent executes in order. Each todo has a title, which names the step, and a description, which says what to do and how: the sources to use, the files to read, and the result the step should produce. A todo can also require your approval before it is executed. In a session, the todos appear in the checklist on the right and are ticked off as they are done.

A todo can also say how the Ask agent should present something to you: ask with a form, draft the email for you to send, or report the result as a work summary. The blocks it can use are described at Interactive blocks.

## Todos

[ ] Send welcome email to new employee
Description: Use the Outlook source to introduce their manager and team, share the first-day logistics, and summarise what to expect in week one. Draft from assets/welcome-email-template.md and assets/week-one-checklist.md.
Approval: required

Example: a todo with a title, a description that names the source and the assets to use, and an approval.

Paths

A path is a group of todos that runs only when the process calls for it, for example the steps to follow when a contractor sends a quote instead of confirming a date. Define each path under ## Paths, with a ### path-name heading and its own todos, and give every path in the file a different name. To run it, write run path path-name in an Instruction, a Rule, a todo title or a todo description, or write a sentence that names the path and says when to run it, for example “if the contractor sends a quote, run quote-approval-flow”.

A process can also run one of your other workflows as a step, with run process process-name. The Ask agent executes that workflow’s PROCESS.md and its todos inside the same session, then continues with the rest of the current process.

## Todos

[ ] Process the contractor's reply
Description: After the contractor responds, run path job-fixed-resolution if the job was fixed. Run path quote-approval-flow if they sent a quote for further work.

## Paths

### job-fixed-resolution
[ ] Email tenant confirming the fix
Description: Use the Outlook source to email the tenant. Draft from assets/tenant-fix-confirmation.md.
Approval: required

[ ] Mark job complete in iamproperty
Description: Use iamproperty to mark the job complete on the ticket.

### quote-approval-flow
[ ] Email landlord requesting quote approval
Description: Use the Outlook source to email the landlord. Draft from assets/quote-approval-request.md.
Approval: required

[ ] Once approved, email the contractor to schedule the work
Description: Use the Outlook source to confirm the approval and ask for a date.
Approval: required

Example: a todo that runs one of two paths depending on the contractor’s reply, and the two paths with their own todos.

Approvals

An approval makes the Ask agent pause before an action and ask you first. You can require it in two places.

• On a todo. Add Approval: required to the todo, and the Ask agent asks before it executes that step. One approval covers the whole step, and if you decline, the step is skipped.
• In an Instruction or a Rule, for actions in general. Write Approval: required together with the kind of action, for example “Approval: required before any email goes to a client”, and the Ask agent asks before every such action, whichever step it happens in.

In both cases the approval arrives in the session as an Input needed block, under Actions needing your approval. Reading data from sources, for example looking up a contact in the CRM, opening an email or reading a file, never needs approval. Only actions that change something do, unless an Instruction or a Rule says otherwise.

## Instructions
Approval: required before any email or message goes to a client.

## Todos

[ ] Send the offer letter
Description: Email the offer letter to the candidate with the Outlook source, drafted from assets/offer-letter.md.
Approval: required

Example: an Instruction that requires approval for every outgoing email or message, and a todo that requires it for one step.

Assets

Assets are the complementary files the Ask agent needs to execute the work, for example a template it fills in or a price list it quotes from. They are stored beside the PROCESS.md in the workflow’s folder, in whatever structure suits you, and you add them in the Assets field when you create the workflow.

lead-qualification/
├── PROCESS.md
└── assets/
    ├── first-response.md
    ├── availability.md
    ├── brand-tone.md
    └── price-list.pdf

Example: a workflow folder, the PROCESS.md with its assets folder beside it.

The Ask agent reads an asset only when the file names it, so mention every asset where it is needed, in the Role, the Instructions or a todo, by its path, assets/price-list.pdf for example, the same way you name a source. A reference in the Role or Instructions applies to the whole process. A reference in a Rule, a todo or a path applies wherever that part runs.

## Instructions
Match the tone in assets/brand-tone.md on anything that goes to a client.

## Rules
Escalate: If the enquiry is outside the areas listed in assets/coverage.md, tell the branch manager.

## Todos

[ ] Send the first response
Description: Draft from assets/first-response.md and offer the slots in assets/availability.md.
Approval: required

[ ] Answer any pricing question
Description: Quote only from assets/price-list.pdf. If it is not in there, run path ask-a-manager.

Example: how a file names its assets, in an Instruction, a Rule and two todos.

When to use an asset and when a source

Use assets when you want to give the Ask agent a resource it needs to execute the work, for example a contract template, an email template, a price list or a checklist, or as a source of information that does not need a large amount of data, for example a short FAQ or the list of areas you cover. For large amounts of information, a manual of hundreds of pages or a whole knowledge base, a Files, Web pages, Google Drive or SharePoint source serves better, because its content is turned into a vector store the Ask agent can search for the answer it needs.

Information the workflow expects to run

Depending on what the PROCESS.md specifies, a workflow may need certain information to run, for example the customer to email, the phone number whose WhatsApp messages to subscribe to, or the quote to open. That information has to be passed to the workflow when it is started, in one of the ways explained below. If you use placeholders in the PROCESS.md, such as {contact name} or {quote reference}, make sure the values are passed when the workflow starts. If the information is to be found through a source instead, say so in the PROCESS.md, for example “open the quote in Street by the reference in the context”.

• Manually. Type it in the Context line of Run workflow.
• Through the API. Pass it in the context field of the request, as Start workflows through the API shows.
• On a trigger. The webhook event of the source that triggers the workflow must pass that information when it starts the session. Learn more at On a trigger.

By default, if information the workflow needs to start or to continue is missing, the Ask agent asks you what to do, as When the Ask agent needs an input explains. If you want something else to happen when required information is not provided, specify it in the PROCESS.md, in the Rules or the Instructions.

Scheduling the next session run

The Ask agent only acts while a session runs and cannot yet set up on its own when the session will continue, so if you specify in a PROCESS.md, for example, “chase again next week” or “if there is no reply in two working days, call the landlord”, the session will not continue at that time by itself. The same result is achieved in another way, explained below.

• Auto-run re-runs the session on a schedule, Hourly, Daily, Weekly or Monthly, until every todo is done. Each run picks up where the last one left off and follows the PROCESS.md again, which is, for example, how a weekly chase happens weekly. The Continuing a session automatically page explains where to switch it on and how often it runs.
• Webhook events resume the session the moment an event happens in one of your sources, for example a reply was sent or a payment was made. The Ask agent can subscribe the session to those events, as the Events section explains. The Continuing a session automatically page explains webhook events.

Both can be used together. Write the follow-ups in the PROCESS.md as a check the Ask agent makes on each run, then set auto-run or subscribe to the events so the session actually continues. The Continuing a session automatically page explains why writing in the PROCESS.md when exactly the session should run again will not work as expected, and how to cover that.

How the Ask agent turns the PROCESS.md into tasks

Invoice chasing · SeptemberEnable auto-run

Ask09:00

The file has no todos, so I planned the steps from the Role and the Instructions: find the unpaid invoices in Street, send a reminder for each with the Outlook source, log every reminder, and check for replies on the next run.

Street CRM09:00

Found 3 unpaid invoices: INV-1042, INV-1051 and INV-1057.

Ask09:01

Sent a reminder for each invoice with the Outlook source. Logging them in Street now.

Type a message…2 sources enabled

Picture: a session started from a file with no todos. The Ask agent says in the feed that it planned the tasks from the Role and the Instructions, and the checklist on the right shows the tasks it created and ticks them off as it works.

When a session starts, the Ask agent reads the whole file, the header, every section and every asset it names, and turns it into a task list before it does anything. The checklist on the right of the session shows that list, and it is ticked off as the work is done. How the list is made depends on what the file gives it.

• Todos are given. The todos are the task list, in the order and with the titles you wrote. The Ask agent adds nothing to it and skips nothing. What a todo needs on the way, looking up a phone number before sending a message for example, happens inside that todo, not as a task of its own. How each todo is executed is explained at How it operates on the Ask agent page.
• No todos. If the Role or Instructions sections are available, and there is enough information about the work that needs to be done, the Ask agent reasons through it and creates the todos based on the available information. If there is not enough context, the Ask agent does not proceed and asks you for the input it needs.
• Paths. A path is not part of the task list at the start. When the Ask agent reaches the todo, Rule or Instruction that runs the path, it adds the path’s todos to the list at that point, works through them, and then continues with the next todo of the main list.
• Rules cut across the list. A Stop rule that matches ends the work whatever is left on the list. An Escalate rule sends its email and the list carries on.
• Not enough to go on. If a PROCESS.md does not contain enough context about the work that should be done, at least a detailed description of the Role, the Ask agent does not proceed and asks you for the input it needs.
• Missing run data. A value that belongs to one run, a customer, an ID, a phone number, a date or an amount, never blocks the planning. The Ask agent creates the todos and asks you for the value when the todo that needs it is reached. It never invents such a value and never searches for one you were meant to provide.

Examples

Three complete files, each written for a different kind of work. Copy the one closest to yours and change the names, the sources and the steps.

Chase a contractor until a repair is scheduled

The weekly chase is delivered by auto-run set to Weekly on the workflow, and the contractor’s reply is picked up through the event it subscribes to.

---
name: contractor-chase
description: >
  Chase a contractor weekly for a response on a logged repair until they confirm scheduling. If the contractor replies with a confirmed date, notify the tenant. Escalate to the contractor-escalation process if still unresponsive after 3 weeks.
---

## Role
Act as an internal property operations coordinator supporting the repairs team.

## Instructions
This process runs against repairs logged by tenants, not by landlords. Contractors are usually slow to reply in the first week, so do not treat silence as a refusal. If the tenant has already chased the contractor directly, acknowledge it so we do not look uncoordinated.

## Events
- outlook / message.received
  where from_email is "repairs@brightfix.co.uk"

## Rules
Stop: If the contractor confirmed a date or the tenant withdrew the repair.
Escalate: After 3 weeks without a response, run process contractor-escalation and notify the property manager at pm@acme.co.
Tone: Keep messages polite and professional. Use a firmer tone on the 3rd attempt.
Language: Always use British English.

## Todos

[ ] Check for contractor response
Description: In iamproperty, look for replies against this repair in the last 7 days.

[ ] Send follow-up message
Description: Use the Outlook source and iamproperty to draft and send a chase email. Draft from assets/contractor-chase-template.md. Reference the original repair and prior messages. If the contractor replies confirming a date, run path tenant-update.
Approval: required

[ ] Log outcome
Description: In iamproperty, record the sent message and next expected response date.

## Paths

### tenant-update
[ ] Email the tenant confirming the scheduled date
Description: Use the Outlook source to send a brief, friendly update with the confirmed date, contractor name, and what to expect on the day. Draft from assets/tenant-scheduled-update.md.
Approval: required

[ ] Log the notification in the repair ticket
Description: In iamproperty, record that the tenant has been informed, with timestamp.

Example: a complete contractor chase file, re-run weekly by auto-run and resumed by the contractor’s reply.

Qualify a new lead and book a viewing

Started by the Street event of a new enquiry, set as the workflow’s trigger. The Ask agent checks the enquiry against the criteria, sends the first response after your approval, and books the viewing once the applicant replies on WhatsApp, the event the file subscribes to.

---
name: lead-qualification
description: >
  Qualify a new rental enquiry from Street against our criteria, send the first response with the matching properties, and book a viewing once the applicant confirms a slot. Decline politely when nothing fits.
---

## Role
Act as a lettings negotiator at Harborview Estates, writing to applicants in the agency's name.

## Instructions
Match the tone in assets/brand-tone.md on anything that goes to an applicant. Offer only properties that fit the budget and the move-in date in the enquiry. Quote prices from assets/price-list.pdf and nothing else.

## Events
- ai-number / message.received
  where contact_phone is the phone number in the enquiry

## Rules
Stop: If the applicant says they are no longer looking.
Escalate: If the applicant asks about fees or deposits that are not in assets/price-list.pdf, email the branch manager at sam@acme.co with the Outlook source.
Approval: required before any message goes to an applicant.

## Todos

[ ] Read the enquiry
Description: In Street, open the enquiry and note the budget, the number of bedrooms, the area and the move-in date.

[ ] Check qualification criteria
Description: Compare the enquiry with assets/qualification-criteria.md. If it does not qualify, run path decline.

[ ] Send the first response
Description: Draft from assets/first-response.md, list the matching properties from Street and offer the viewing slots in assets/availability.md. Send it with the WhatsApp (AI Number) source.

[ ] Book the viewing
Description: When the applicant confirms a slot, create the viewing in Street and confirm it to them with the WhatsApp (AI Number) source.

## Paths

### decline
[ ] Let the applicant know
Description: Send a short, friendly message with the WhatsApp (AI Number) source, drafted from assets/decline.md, and mark the enquiry as not qualified in Street.

Example: a complete lead qualification file, started by a Street enquiry, with an approval rule, a WhatsApp reply event and a decline path.

Remind a customer about an unpaid invoice

Started manually, with the invoice number as context. Auto-run set to Daily on the workflow makes the session check every day whether a reminder is due, and the customer’s reply in the Outlook source resumes it at once.

---
name: invoice-reminders
description: >
  Remind a customer about an unpaid invoice every three days until it is paid, and stop as soon as the customer replies. Runs for one invoice at a time, with the invoice number given as context.
---

## Role
Act as an accounts assistant for the finance team, writing to customers in the company's name.

## Instructions
Check the invoice in Street at the start of every run. Send a reminder only if the invoice is still unpaid and three full days have passed since the last reminder. Otherwise do nothing and wait for the next run.

## Events
- outlook / message.received
  where the sender is the customer on the invoice

## Rules
Stop: If the invoice is marked paid in Street.
Escalate: After the third reminder without a reply, email the finance manager at finance@acme.co with the Outlook source and stop the reminders.
Tone: Polite and short. The third reminder may say that the account will be passed to the finance manager.

## Todos

[ ] Check the invoice
Description: In Street, open the invoice from the context and note its status, the customer's email address and the date of the last reminder.

[ ] Send the next reminder if it is due
Description: If the invoice is unpaid and three full days have passed since the last reminder, draft the next reminder from assets/reminders.md and send it with the Outlook source. Log the reminder in Street.

[ ] Handle the reply
Description: When the customer replies, answer their question or confirm the payment date, log the reply in Street, and stop the reminders.

Example: a complete invoice reminder file, re-run daily by auto-run, with the reminder written as a check and the customer’s reply as the event.

Run it in Askpilot

To run a PROCESS.md you have written, you need to create a workflow from it and run it. Follow these steps.

1. Create the workflow. Learn more at Create a workflow.
2. Run the workflow. Learn more at Start a workflow.

Guidelines, good practice and tips

A few habits make any workflow run well, whatever the process.

• Keep the file lean. Leave out background that would not change what the Ask agent does, how it does it or what it returns. It has to weigh every line, so a shorter file runs more reliably. Instead of “Our company was founded in 2012 and prides itself on great service and a personal touch. Reply to every enquiry within the hour”, write “Reply to every enquiry within the hour”.
• Keep long or shared material in assets. A price list, a template or a policy belongs in a file beside the PROCESS.md, named where it is needed, so the todo stays short and the file can change without the process changing. Learn more at Assets.