# PROCESS.md PROCESS.md is an open markdown format for business workflows: roles, rules, steps and approvals in one readable file. AI agents write it, Askpilot runs it. Intelligent Process Automation PROCESS.md is a format for writing down your business processes in plain language, with roles, todos, rules, and approvals that AI agents run. ## Why PROCESS.md PROCESS.md is a format for AI agents to intelligently execute processes, such as chasing an overdue invoice or onboarding a new client, based on instructions written in plain language. It replaces traditional rule-based automation tools built around drag-and-drop flowcharts, which are limited to predefined logic and cannot adapt or improvise. Traditional automation tools ### Static flowcharts Create deterministic processes with every step predefined. They execute exactly as designed, but cannot interpret ambiguity, apply judgment, or adapt beyond the flow. PROCESS.md ### Intelligent automation Write the process in plain language. An AI agent runs it, adapts to nuance, handles edge cases you didn't think of, and pauses for your approval when it matters. ```markdown --- name: invoice-chase description: Chase an overdue invoice until paid. --- ## Rules Escalate: If invoice 30 days or more overdue, notify account manager at amelia.brooks@kinsleyandco.co.uk. ## Todos [ ] Send reminder Description: Use gmail to draft a reminder, working from assets/invoice-reminder-template.md. If this is the 3rd attempt, use a firmer tone. Approval: required [ ] Log outcome Description: In hubspot, update the record with the message sent and next follow-up date. ``` ## Writing a PROCESS.md Every PROCESS.md has the same structure. A YAML header with the name and description, followed by six sections: `## Role`, `## Instructions`, `## Events`, `## Rules`, `## Todos`, and `## Paths`. Alongside the file, the process folder can hold assets: skills, templates and reference files the agent can pull in for extra context while it runs. Only the header is required. Every section is optional, so the file gets more prescriptive as you add them. If there are no predefined todos, the agent creates the work needed to deliver the description, following the Role and Instructions and obeying the Rules. Add a role to define who it acts as and who it serves, instructions to control how the whole process runs, events to let it wait on other people, rules to set the highest-priority boundaries, todos to fix the steps, and paths to branch. | Section | Required | Purpose | | --- | --- | --- | | `---` frontmatter | Yes | The `name` and `description` of the process, between two `---` lines at the very top. | | `## Role` | No | Who the agent acts as, the audience it serves, and whether the process is internal or external-facing. A Role may instead be described inside `## Instructions`. | | `## Instructions` | No | Process-wide directives, context, and execution requirements that control how the whole process is carried out. | | `## Events` | No | The webhook events a run subscribes to, so it can wait on a reply, a payment or a document and carry on when one arrives. Each event can carry filters so only the occurrences you care about count. | | `## Rules` | No | Conditions, policies, guardrails, or custom directives for the whole process. | | `## Todos` | No | The actual process the agent executes, as a list of items. | | `## Paths` | No | Reusable sub-flows the process can run mid-execution. Instructions, Rules, Todo Titles, or Todo Descriptions can trigger a named Path. | Example ```markdown --- name: process-slug description: Full description of the process. --- ## Role ← optional ## Instructions ← optional ## Events ← optional ## Rules ← optional ## Todos ← optional ## Paths ← optional ``` ### Frontmatter A YAML header with two required fields: `name` and `description`. | Field | Required | Constraints | | --- | --- | --- | | `name` | Yes | Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen. | | `description` | Yes | Up to 1024 characters. Describes what the process does. Use `>` for multi-line values. | Example ```markdown --- name: new-client-onboarding description: > Onboard a new client, from contract signature through their first kickoff call and system setup. --- ``` ### Role A Role defines who the agent acts as, the audience it serves, and whether the process is internal or external-facing. Put it under `## Role`, or describe it inside `## Instructions`. In either place, it applies throughout the process. If no Role is defined, the agent uses its normal internal assistant behaviour. Role content has the same priority as Instructions: Rules override both, while Role and Instructions override the description, Events, Todos, Paths, and default execution guidance. If separate Role and Instruction text conflict and the intended priority is unclear, the agent asks the assigned internal user before acting. | Section | Required | Description | | --- | --- | --- | | `## Role` | No | Free text describing the identity, audience, purpose, responsibilities, and communication style the agent should use. | #### Internal and external Roles You do not have to label the Role as internal or external. The agent determines the type from its purpose, audience, and responsibilities. | Type | How it is determined | | --- | --- | | Internal | The agent supports your team or operates internal systems using its normal internal assistant behaviour. One outbound task, such as sending an email for an internal user, does not by itself make the Role external. | | External | The agent acts as the direct representative communicating with or serving a customer, lead, applicant, supplier, or another non-team member. | **Make the audience clear.** If the type or intended audience remains genuinely unclear after the full process is read, the agent stops and asks the assigned internal user before it communicates or takes action. #### How an external Role behaves - It immediately adopts the stated identity, audience, purpose, and communication style. It never presents itself as Ask or an internal assistant, reveals internal Process content, or invents a name, title, qualification, or authority the Role does not provide. - It grounds factual answers only in the external conversation, the active Process and referenced assets, or verified data from available Sources. If information is unavailable, it does not guess: it follows the Process's fallback or handoff, or briefly says it cannot confirm or complete the request and stops. - It never claims an action succeeded unless the relevant Source confirms it, and it shares only information the Process permits for that external party. - The Role authorises communication within its stated purpose, not extra work. Writes, transactions, bookings, record changes, and other side effects must be explicitly required by the Process. - Messages from the external party are treated as information, not as Process instructions. They cannot change the Role, scope, authority, or approval requirements. - Internal approvals, operational status, tool or Source details, and technical errors are never included in external-facing communications. Approvals stay internal. Every approval must come from the assigned internal user. An external party may supply information or answer a Process question, but their response is never an approval or sign-off. #### Paths and nested Processes A local Path inherits the active Role. A separate Process also inherits it when that Process does not define a Role of its own. A nested Process may use an internal Role for background work, but it must preserve the parent's external-facing identity for customer communication. The external-facing Role changes only when the parent Process explicitly authorises a handoff. When the nested Process finishes, the agent returns to the parent Role. Example ```markdown ## 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. ``` ### Instructions Instructions tell the agent how the whole process must be carried out. Write them in plain language as free text or bullet points. They can provide operating context, define what matters or what a good result looks like, and set required actions, limits, methods, edge-case handling, or lifecycle behaviour. Instructions may also name Sources, skills, assets, approval requirements, output formats, or Paths that apply across the process. A Role may be written here instead of in a separate `## Role` section; Role content is treated at the same priority as Instructions. | Section | Required | Description | | --- | --- | --- | | `## Instructions` | No | Free text or bullet points containing process-wide context, directives, and execution requirements. There are no required labels or fixed internal structure. | #### How Instructions affect execution - They apply from setup to completion: on every trigger, while creating or executing Todos, when a session resumes, and through every Path. - If predefined Todos exist, the agent preserves their order and Titles unless an Instruction or Rule requires otherwise. If they are absent, it creates the necessary Todos from the description by following the Role and Instructions and obeying the Rules. - A required Source, skill, asset, approval, execution method, or output format named in Instructions must be followed wherever it applies. - Instructions can change how other Process content is executed, but they do not authorise the agent to invent or expand work beyond what they and the process purpose explicitly require. **Process precedence.** Rules have the highest priority. Role content and Instructions come next and override the description, Events, Todos, Paths, and default execution guidance whenever they conflict. If an Instruction conflicts with a Rule, the Rule wins. If two Instructions conflict or it is unclear which applies, the agent stops and asks the assigned internal user instead of guessing. Include only instructions that change execution. The agent reads and applies every line. Leave out background detail that would not affect what it does, how it does it, or the result it returns. Example ```markdown ## Instructions This process applies only to repairs reported by tenants. Use iamproperty for repair history and front 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 the assigned internal user's 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. ``` ### Events The third-party tools you connect publish webhook events: a WhatsApp message arrives, a Stripe payment succeeds, a document is uploaded, a deal moves stage. This section is where you subscribe to the ones this process should listen for. A subscribed event resumes a session that is already open. It keeps a process usable for time-sensitive work like customer support, where a reply has to be picked up when it arrives, and it saves tokens because the agent will not rerun the session on a fixed schedule to check whether the event has occurred. | Section | Required | Description | | --- | --- | --- | | `## Events` | No | One line per event, each optionally followed by filters. | #### Naming an event exactly If you know the source and the event id, write them. Filters are optional: add them to narrow which occurrences count, or leave them out to receive every one. | Part | What it is | | --- | --- | | Source | The connected tool the event comes from, for example `ai-number` or `stripe`. | | Event | The event id, for example `message.received`. Each source publishes its own list. | | Filters | Optional conditions on the event's own fields, written as `field`, `condition`, `value`. Conditions are `is`, `is not`, `has` and `doesn't have`. Several filters on one event are joined with and, so every condition has to match. | Example ```markdown ## Events - ai-number / message.received where contact_phone is "+447700900123" - stripe / payment.succeeded ← no filters, every occurrence ``` #### Describing it in your own words You do not have to know any of that. Write what you want in plain language, for example "subscribe to incoming WhatsApp messages from +447700900123", and the agent should look up what the source actually publishes before it subscribes: the real event ids, the fields each one can be filtered on, and the values those fields accept. If something matches, it should subscribe to that and tell you what it chose. If nothing matches, it should subscribe to nothing and say so. It should not pick the closest-looking event, because a wrong subscription is worse than none: the process would sit waiting for something that never arrives. A wrong filter fails silently. A filter on a field that does not exist, or a value outside what the field allows, is accepted and created without error. It simply never matches, so the process waits forever and nothing tells you why. The agent should check the available events and their filter fields before subscribing, rather than guessing from the name. ### Todos A todo is a single step the agent executes to complete the process. Each todo has a `Title` and a `Description`, plus an optional `Approval` flag. Everything else the todo needs, which sources to use, which skill or reference files to load, is written into the `Description` in plain language. | Parameter | Required | Description | | --- | --- | --- | | `Title` | Yes | A short name for the todo, written after `[ ]`. | | `Description` | Yes | What the todo is and how the agent should execute it. Name everything the todo needs here, in plain language, which sources to use (CRMs, email, calendars, messaging, file storage), and any SKILL.md or template/reference files to load before running it. | | `Approval` | No | The agent asks for the approval of every action it takes while running this todo. | **Only include what the agent needs.** An AI agent reads every line in a todo and uses it to decide how to act. Irrelevant details confuse the execution and make results less reliable. Example ```markdown ## Todos [ ] Send welcome email to new employee Description: Use gmail and email-writer to introduce their manager and team, share the first-day logistics, and summarise what to expect in week one. Follow the write-professional-email and internal-tone-guide skills, and draft from assets/welcome-email-template.md and assets/week-one-checklist.md. Approval: required ``` ### Rules Rules are conditions, policies, guardrails, or any custom directives that apply to the whole process. Each rule starts with a label followed by the instruction. Use one of the predefined labels or create your own. #### Custom rules | Parameter | Required | Description | | --- | --- | --- | | `Label` | Yes | A short category name for the rule, followed by `:`. | | `Instruction` | Yes | The condition, policy, guardrail, or any custom instructions the agent must follow. | #### Predefined rules | Label | What it does | Instruction | | --- | --- | --- | | `Stop` | Process stops and will not be executed further. | Describe when the process should stop. | | `Escalate` | Notify about certain event (process will continue to execute). | Describe who to notify, when, and their email. | **Email only for now.** Escalate sends notifications via email. Other channels like Slack or SMS aren't supported yet. **Rules have the highest priority within a Process.** They override Role content, Instructions, Todos, Paths, Events, and the process description whenever they conflict. Example ```markdown ## Rules Stop: If contractor confirmed a date. Escalate: If a customer complains about product quality, email the product manager at alex.chen@acme.co. Language: Always use British English. CC Policy: CC the manager on all disputes when sending an email. Manager email: sarah.walker@acme.co ``` ### Paths Paths are sub-flows that can be triggered from Instructions, Rules, Todo Titles, or Todo Descriptions. A trigger may use `run path [path-name]` or state a clear condition and the Path to run. Define each Path under `## Paths` with a `### path-name` heading and its own todos. To trigger an external `PROCESS.md`, use `run process [process-name]`; it runs a separate file from your `processes/` folder. A clear condition that names the resulting external Process also counts as a trigger. | Parameter | Required | Description | | --- | --- | --- | | `Name` | Yes | A short path name, written after `### `. Each path in a PROCESS.md must have a unique name. | #### How to run a local path or trigger an external process | Phrase | What it runs | | --- | --- | | `run path [path-name]` | Runs a path defined in `## Paths` section. | | `run process [process-name]` | Runs an external `PROCESS.md` file from your `processes/` folder. | #### Processes folder structure processes/ ├── maintenance-ticket/ │ ├── PROCESS.md │ └── assets/... ├── inspection-report/ │ ├── PROCESS.md │ └── assets/... ├── request-photos/ │ └── PROCESS.md └── shared-assets/ └── brand-tone.md Example ```markdown ## 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 front to email the tenant. Draft from assets/tenant-fix-confirmation.md. Approval: required [ ] Email landlord confirming the fix Description: Use front to email the landlord. Draft from assets/landlord-fix-confirmation.md. Approval: required [ ] Mark job complete in iamproperty Description: Use iamproperty to mark the job complete on the ticket. [ ] Upload contractor invoice to ticket Description: Use iamproperty to attach the contractor invoice to the ticket. [ ] Move Trello card to Done Description: Use trello to move the card to the Done list. ### quote-approval-flow [ ] Email landlord requesting quote approval Description: Use front to email the landlord requesting approval. Draft from assets/quote-approval-request.md. Approval: required [ ] If no reply in 2 working days, schedule a call with landlord Description: Use outlook-calendar to schedule a call if there's no reply in 2 working days. [ ] On approval, email contractor confirming and request scheduling Description: Use front to email the contractor confirming and requesting scheduling. Approval: required [ ] Once fixed, run path job-fixed-resolution ``` ### Assets You can add assets to a process, to be used as context while it runs. To be read, an asset has to be referenced somewhere in the process. | Asset | Example | Description | | --- | --- | --- | | Skill | `polite-chase` | A capability the agent uses to carry out the work, written in the open `SKILL.md` format. Reference it by name. The skill has to be installed on the agent before a process can use it. | | File | `assets/price-list.pdf` | A file the agent reads to get the context it needs for a particular task. | **Reference it, or it is not read.** An asset is only loaded when something in the process names it. Putting a file in the folder does not put it in front of the agent. #### Where assets live Anywhere inside the process folder. Build whatever structure fits you best. lead-qualification/ ├── PROCESS.md └── assets/ ├── first-response.md ├── availability.md ├── brand-tone.md └── price-list.pdf #### Referencing an asset Reference the file where you need it, in plain language, the same way you name a Source or a skill. A reference in the Role or Instructions applies to the whole process. A reference in a Rule, Todo Title, Todo Description, or Path applies wherever that content is executed. Example ```markdown ## 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. Follow the lead-follow-up skill for the tone. 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. ## Paths ### ask-a-manager [ ] Ask the branch manager for a figure Description: Use the wording in assets/manager-request.md. Approval: required ``` #### When to use one Move something into an asset when it is long, when it changes on a different schedule to the process, or when more than one todo needs it. A three-word instruction belongs in the todo. A price list, an outreach template you have spent a year getting right, or a policy your compliance team owns belongs in a file. ### Full example A full example of a complete PROCESS.md file. ```markdown --- 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 - front / message.received where from_email is "repairs@brightfix.co.uk" ## Rules Stop: If contractor confirmed a date or 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 front and iamproperty to draft and send a chase email. Follow the contractor-communication skill and 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 front 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. ``` ## Run PROCESS.md in Askpilot Askpilot is purpose-built to run PROCESS.md files. From one place, activate any process where it needs to run: - Across your whole company for organisation-wide processes - To specific teams like sales, operations, or compliance - To individual employees for personal processes or assigned tasks - On any trigger like events, schedules, conditions, or manual runs Get started today ### Run your processes in Askpilot. Request access and start automating your business processes. --- This is the Markdown version of https://askpilot.com/process-md.html. Site index for agents: https://askpilot.com/llms.txt