Document Format Reference

Complete reference for the procedure document format — every section, field, and convention.

Full Template

id: my-procedure
version: 1.0
trigger: manual
category: Operations
description: One to two sentences describing what this procedure does and when to use it.
access: public
admins:
  - slack:#ops-team
share:
  - slack:#all-employees
 
# My Procedure
 
One to two sentences describing what this procedure does and when to use it.
 
## Input
 
| Field | Type | Required | Default | Description |
|-------|------|----------|---------|-------------|
| field_name | string | yes | | What this field is for |
 
## State
 
| Field | Storage | Description |
|-------|---------|-------------|
| current_step | invocation | Where we are |
 
## Steps
 
### first_step
Description of what to do.
 
→ next_step
 
### next_step
Description of what to do.
 
→ done ✓
 
### done ✓
Close the run.
 
## Output
 
| Field | Type | Description |
|-------|------|-------------|
| result | string | What was produced |

Frontmatter Fields

Field	Type	Required	Values
`id`	string	yes	Unique, kebab-case identifier
`version`	string	yes	`major.minor` — start at `1.0`, LLM bumps based on edit nature
`trigger`	string	yes	`manual`, `schedule("0 9 * * MON")`, `event("type")`
`category`	string	yes	Finance, People, Procurement, Access, Compliance, Operations, Custom
`description`	string	yes	User-facing summary — what it does and when to use it
`access`	string	yes	`public` (discoverable by all) or `private` (only shared principals)
`admins`	list	yes	Principals who can manage, edit, and view all runs
`share`	list	no	Principals who can discover and invoke (for `private` procedures)

Principal Formats

Format	Example	Resolves to
`slack:#channel`	`slack:#finance-team`	All members of the Slack channel (dynamic)
`email:addr`	`email:alice@co.com`	Single user by email
`user:id`	`user:abc123`	Single user by Gateway ID

Input Field Types

Type	Description	Example
`string`	Text value	`"Fix the login bug"`
`number`	Numeric value	`85.50`
`date`	ISO date	`2026-03-15`
`boolean`	True/false	`true`
`string[]`	List of strings	`["alice", "bob"]`
`object`	Structured data	`{ name: "...", email: "..." }`

State Storage Types

During execution, all state lives in D1. On run completion, collections export to Notion.

Storage	Use For	In-Flight (D1)	On Export (Notion)
`Notion DB`	Collections the user should see	`run_submissions` rows	Notion DB under procedure page
`Notion DB: {auto}`	Collections where AI designs the schema	`run_submissions` rows	Auto-created Notion DB
`Notion DB row`	Single row in an existing database	`run_submissions` row	Notion DB row
`invocation`	Scalar values for internal tracking	`runs.current_step` etc.	Run metadata in Notion

Step Patterns

Simple Transition

### create_record
Create the record in the database.
Notify the submitter.
 
→ review

Approval with Escalation

### approve
Post in #channel for approval.
- If amount ≤ $200 → team lead approves
- If amount > $200 → department head approves
 
**Wait**: 48h
**On event** `approved`: → next_step
**On event** `rejected`: → rejection_step
**On timeout**: Escalate — ping approver again, CC their manager.

Collect Over Time

### collect_responses
**Wait until**: {input.deadline}
**On event** `response`: Add to {state.responses}. Confirm to sender.
**On timeout**: Continue with whatever was collected.
 
→ process

Branch by Condition

### route
Based on {state.decision}:
 
**If approved:**
- Create Linear issue
- → execute
 
**If rejected:**
- Notify submitter
- → done ✓
 
**If deferred:**
- Schedule reminder for 3 months
- → done ✓

Periodic Check-in

### track_progress
**Wait until**: {input.target_date} - 14d
 
Weekly on Monday:
- Query status from Linear / Notion
- Post update in {input.channel}
- Flag blocked items
 
**On event** `ready`: → next_step

Multi-System Provisioning

### setup_accounts
Create or verify:
- Google Workspace account
- Slack invite → add to channels
- Notion access → share team spaces
- Linear team membership
- GitHub access (if engineering)
 
Create checklist in Notion to track completion.