What is PROCESS.md?
PROCESS.md, introduced by Askpilot, teaches AI agents how your business operates. You describe what needs to be done in plain text, and agents use it to create todos, execute them in order, and ask for help when needed.
Think of it as writing down the instructions you'd give a new team member on their first day. "Here's how we handle a maintenance request." "Here's how we renew a tenancy."
If you can write a checklist, you can write a PROCESS.md.
Why PROCESS.md?
Built for business processes
Structured around pipelines, tasks, deadlines, and approvals. Exactly the way your business already operates.
Turns workflows into todos
Agents read your process and automatically create todos they can follow, complete, and report on.
Human readable
Plain text that anyone on your team can read, write, and understand. No technical knowledge required.
No complex syntax required
No programming, no special syntax. If you can write a checklist in a text file, you can write a PROCESS.md.
Progressive complexity
Start with a simple checklist. Add task groups, stages, pipelines, and supporting resources only when your process demands it.
Built-in guardrails
Human-in-the-loop approval is part of the format. Mark any step as requiring human sign-off before the agent acts.
The format
Every PROCESS.md starts with a YAML header. Agents read the name and description to understand what the process does before executing any steps.
Every process is made of todos. A todo is a single item that needs to be completed. Each todo moves through three statuses: pending, in_progress, and completed.
Anatomy of a todo
Every todo has a title and a description, plus optional context parameters.
Context parameters
Approval
Approval: required
A human must approve before the agent acts on this step
Agents
Agents: name, name
Which agent to use for this todo
Assets
Assets: assets/file.md
A template, reference, or example to load as context
Only add what's needed. Every todo needs a title and a description. Use context parameters when the agent needs to flag human approval, assign agents, or reference assets.
Scales with your process
Start with the simplest approach that works. You can always add structure later.
Quick checklist
A flat list of todos in one file. Perfect for quick procedures and simple checklists.
Task groups
Organize todos into named groups. The agent uses group names to understand what each set of todos relates to.
Full pipeline
When your process is a pipeline with clear phases. Define the stages, assign tasks to each one, and track where every item is.
A full pipeline has three components:
Stages
The columns of your pipeline. Each stage represents a phase of work (e.g. Valuation, Marketing, Move In).
Task files
Each stage links to .md files in a tasks/ folder. Each task file contains the todos for that part of the process.
Assets
An optional assets/ folder with templates, references, and examples. Agents load these as context when executing todos.
Real-world example
A property letting lifecycle. From landlord acquisition through tenant move-in. Six stages, 24 task files.
Stage 1
Brand Marketing
3 tasks
Stage 2
Valuation
4 tasks
Stage 3
Instruction
3 tasks
Stage 4
Marketing
5 tasks
Stage 5
Pre-booked
5 tasks
Stage 6
Move In
4 tasks
Example task file: tenant-referencing.md
Full directory structure
Specification reference
The full technical specification for agents creating and executing PROCESS.md files.
Frontmatter
Every PROCESS.md file begins with YAML frontmatter between --- marks. Two required fields:
- •
name— a unique identifier for the process (lowercase, hyphenated) - •
description— what the process does. Agents read this first to understand scope.
File format
- • PROCESS.md uses YAML frontmatter (between
---marks) with exactly two fields:nameanddescription - • All content after the frontmatter is plain markdown
- • Todos are markdown checkboxes:
- [ ](incomplete) or- [x](complete) - • Todo descriptions are indented plain text below the checkbox line
- • Context parameters are indented lines using the format
FieldName: value. Recognised parameters:Approval,Agents,Assets - • Task notes are blockquotes (
>) placed at the top of a task file, before the first todo - • Labels are markdown H2 headings (
##) that group todos - • Stages are defined in a markdown table with columns: Stage, Tasks
- • Task files contain an optional task note (blockquote), then todos. No YAML header needed.
Hierarchy
Naming conventions
- • Process name: lowercase, hyphenated (e.g.,
property-letting-lifecycle) - • Task files: hyphenated name with
.mdextension (e.g.,qualify-lead.md) - • Task names in stages table: the file name including
.mdextension, separated by commas
Directory structure
Quick checklist / Task groups:
Full pipeline:
Todo structure
Rules for agents
- 1.Always start by reading the process
descriptionto understand scope - 2.When stages exist, read the stages table first to understand the pipeline
- 3.Task files listed in the stages table are located in the
tasks/folder next to PROCESS.md - 4.The order of tasks within a stage is determined by their order in the stages table (left to right)
- 5.Execute todos in the order they appear, top to bottom
- 6.Load task files only when working on that specific stage
- 7.Read the task note (blockquote at the top of a task file) before executing any todos
- 8.Every todo has a title and a description. The description explains how to complete the step. Read both before acting.
- 9.When
Approval: requiredis present, pause and ask a human to approve before acting - 10.When
Agents:is present, use the named agents to execute the todo - 11.When
Assets:is present, load the file from theassets/folder and use it as context - 12.Track each todo's status: pending, in_progress, or completed
- 13.Track which stage each item is in
- 14.If a todo cannot be completed, flag it and do not skip it
- 15.Labels give context but do not enforce execution order
How Askpilot uses PROCESS.md
Askpilot reads your PROCESS.md files and uses them to guide your team through every step of their work.
You write a PROCESS.md
Describe your workflow in plain text. Each step becomes a todo an agent can execute.
Askpilot reads and understands it
Askpilot learns your workflows, rules, and way of working. It knows every stage, every step, and when to ask for help.
Your team gets guided through step by step
When a task is assigned, Askpilot walks your team through each todo. It prepares the work, flags what needs attention, and asks for approval when required. Nothing gets missed.