Agents are folders

An agent on foldrun is a folder. Inside it is an AGENT.md with a few lines of frontmatter and a paragraph or two of instructions, and next to it, optionally, tools/, skills/, knowledge/, evals/. A flow is a markdown file with a numbered list. A workspace is a git repository that holds some of each.

That is the whole format. There is no DSL, no graph editor, no YAML pipeline with a schema you have to look up. If you can read a README you can read a desk of sixty agents and know what each one is for.

Why a folder

We arrived at it by running a business, not by designing a product. The people who knew the work — what a good inspection report looks like, which keywords matter in Geelong, what counts as a lead — were not engineers. When an agent was a Python class they could not change it. When it was a paragraph in a file they could, and did, and the paragraphs got better faster than any code we wrote.

A folder also has properties that turn out to matter more than they sound:

• It diffs. Every change to an agent is a commit with an author and a message. When a run goes wrong, git log on the agent tells you what changed and when.
• It copies. A skill that eleven agents share is one folder in the account library. A new workspace is a clone.
• It runs anywhere. The same folder runs under the CLI on a laptop, on our cloud, or on your cluster. Nothing is converted, because there is nothing to convert.
• Claude Code already speaks it. A .claude/agents/*.md subagent deploys as-is; the frontmatter keys we read are a superset.

What it cost

A folder is not a type system. Two things you get for free from code — that a required field is present, and that a reference points somewhere — you have to build for markdown. So we did: foldrun check reads every file in the workspace and refuses to deploy one whose tools: names a tool that does not exist, whose flow cites a step that is not defined, whose verify: has a regex that does not compile. Six tests fail our own build if a documented key is missing from the checker.

The other cost is that a paragraph is ambiguous where a function signature is not. We have leaned into that instead of fighting it. The instructions are for the model; the constraints — which tools, which model, which budget, what the step must produce before the next one runs — are frontmatter keys with exact meanings. The paragraph can be vague. The keys cannot.

The rule we did not break

There was a moment, around the time we added output: json and wait: event, when it would have been easier to add a second format for “advanced” flows. We did not, because the value of the folder is that there is one thing to learn. Every feature since has had to answer the same question: can this be a key in frontmatter or a line in a numbered list? So far the answer has always been yes.