Σ 0:00▸ 0:00

Module 4 · Planning, Context & Multi-agent Systems · scripted

The Task Is a Directory

by Jules White

30 minoutcomes: multi-agent, agent-architectures
🎤 Talk view← Course

Overview

A decomposition tree is a diagram; make it physical, with the most load- bearing pattern in serious agent work: give every task a directory. The brief, the bar, the work, the evidence — each a file in the right room; subtasks as subdirectories, the same shape recursively. And the deep move: the filesystem becomes the medium between conversations — any agent dropped anywhere in the tree self-briefs by reading, every wall is reconstructible from files, and the amnesia stops mattering because the conversation's world, for once, is durable. The task stops living in any transcript, and starts living in the world.

Task decomposition

Start with the idea this whole pattern builds on. Task decomposition is breaking one large task into smaller subtasks that can be worked on separately, and then composing the pieces back into the whole. Nothing about it is special to computing — it is how humans have always organized work. Three co-authors do not write a paper by holding one pen:

Decomposing a paper

Each author works alone on a piece; the pieces have to fit back together at the end. That is the whole idea:

Task decomposition

Break one large task into subtasks that can be worked on separately. Compose the finished pieces back into the whole.

For agents, we decompose for two specific reasons:

Why agents decompose

parallelismindependent subtasks can run at the same time — many agents working at once, like co-authors writing their sections simultaneously
isolated contexteach agent's conversation carries only its own subtask — the whole job never has to fit into one conversation

And the moment the work is divided, the co-authors' problem appears: coordination. Where does each worker learn its assignment and its constraints? How does it hand its finished piece back? How does it see the parts of the others' work it depends on — the section it must not contradict, the interface it must deliver to? For human co-authors, the answer is shared documents in a shared folder. For agents, the answer is exactly the same, and it is this lesson's pattern:

The pattern

Represent the task — and its decomposition — as a tree of directories in a file system, and let the files be how the agents coordinate.

From tree to filesystem

The decomposition tree we just built was a diagram. Here is how real systems make it physical — a pattern so natural it feels obvious the moment you see it:

The mapping

the task            →  a directory
its brief           →  a file of rich context (TASK.md)
its bar             →  a file of what must be true (CHECK.md,
                       plus check.sh when the bar is executable)
the work            →  files created inside, as it happens
its completion      →  a result file, written at the end
                       (RESULT.md)
its subtasks        →  subdirectories — same shape, recursively

The tree of tasks becomes a tree of folders.
Everything about the work becomes a document in the right room.

Anatomy of one task directory

A leaf, opened up

portal/ingestion/ntnu-adapter/
├── TASK.md"Build the adapter for NTNU's nightly feed.
│Context: their format quirks (two headers,
│fathoms, local time)… must deliver to the
│A2-v1 interface (../schema/INTERFACE.md).
│Out of scope: retry logic (parent owns it)."
│
├── CHECK.md"Done means: conformance script passes on all
│three samples; all rows UTC + meters; zero
│silent row drops — rejects must be logged."
├── check.shruns the conformance suite → PASS/FAIL + log
│
├── work/parse.py · notes.md · sample-runs/…
│
└── RESULT.md(absent — this task is not done)

Three documents define the task: what it is, what true means, and — when it exists — what happened. The work directory is scratch; the three documents are the contract.

Notice what the two top files really are. TASK.md is the brief from the seam contract — rich context, self-contained, the child asks no questions. CHECK.md is the evidence bar — and giving it an executable form, check.sh, is the hard-evidence principle made into a file you can run. The directory is the seam contract, written down where the work will happen.

An agent is spawned into a room

Now the coordination move: to work on a task, spawn an agent whose world is that directory. Its first act is always the same — read the room:

Example 1 · Working the leaf
user

You have the following tools available for use:

  1. read_file
  2. write_file
  3. run_command — scoped to this directory (plus read access to ../schema/)

Task: You are working in portal/ingestion/ntnu-adapter/. Read your task, do it, verify it, and write your result.

assistant
read_file(path = "TASK.md")
user
[the brief: format quirks, the A2-v1 interface pointer, scope]
assistant
read_file(path = "CHECK.md")
user
[the bar: conformance on 3 samples, UTC/meters, no silent drops]
assistant
write_file(path = "work/parse.py", content = "[the adapter]")
user
OK. work/parse.py written.
assistant
run_command(cmd = "./check.sh")
user
FAIL: sample-3: 2 rows dropped without log entries (trailing
summary rows discarded silently).
assistant
write_file(path = "work/parse.py", content = "[logs rejected
rows explicitly]")
user
OK. work/parse.py updated.
assistant
run_command(cmd = "./check.sh")
user
PASS: 3/3 samples · 4,112 rows · UTC/meters confirmed ·
rejects logged (2). Log: work/sample-runs/run-9.log
assistant
write_file(path = "RESULT.md", content = "Adapter complete at
work/parse.py. Evidence: check.sh PASS 3/3 (run-9.log).
Note for parent: NTNU's summary rows are data-like — flagged
as rejects, worth a rule upstream.")
✎ noteThe whole loop happened in the room: brief read from a file, bar run as a script, a failure caught and fixed before anyone else ever saw it, and completion written as a document — with evidence attached and one observation passed upward. The agent arrived knowing nothing and oriented itself entirely by reading. That property — the workspace explains itself — is the pattern's quiet superpower.

The hierarchy is the visibility

Climb up a level and see what the folder tree is really doing:

The tree, as a coordination structure

portal/
├── TASK.md · CHECK.md · RESULT.md?
├── ingestion/
│├── TASK.md · CHECK.md · RESULT.md ✓
│├── ntnu-adapter/ RESULT.md ✓
│└── schema/ RESULT.md ✓ · INTERFACE.md
├── frontend/
│├── TASK.md · CHECK.md · (no RESULT.md — in progress)
│├── map-view/ RESULT.md ✓
│└── api-client/ (no RESULT.md — reopened after
│the joint test)
└── docs/RESULT.md ✓
ORGANIZATIONthe decomposition is readable as `ls -R`
ISOLATIONa spawned agent's scope is its subtree — frontend's scratch never enters ingestion's world; siblings meet only through declared files like INTERFACE.md
VISIBILITYparents read children's RESULT.md — never their work/ scratch. Status is not a report anyone writes; it is the presence or absence of files.

This is the placement discipline, implemented by a filesystem. Scope-by-subtree is carry/fork/file with mkdir: the child's wall holds its room; the parent's wall holds result files, one line and a handle each. And the coordinator's completion sweep is almost embarrassingly simple:

Completion, as a directory walk

"Which subtrees are done?" is not a judgment call —
it is a find command:

  done      = RESULT.md present AND its evidence green
  open      = TASK.md without RESULT.md
  suspect   = RESULT.md present, check now failing
              (the world moved — reopen the room)

The project's status dashboard is the tree itself.

Why files

Step back and ask why this pattern keeps winning, and the answer is the course's oldest thesis wearing work clothes: everything is a document — so let the work be documents.

What the filesystem buys

HUMAN-READABLEyour project manager can open the folder. Every brief, bar, and result is prose a human can audit — the legibility thread, now covering the whole project.
DURABLEconversations end; directories don't. The workspace survives every amnesia — memory, without a memory system.
ORIENTINGany agent (or new collaborator) dropped anywhere in the tree can self-brief by reading — the library principle, where the library is the project itself.
ADDRESSABLEevery artifact has a path — handles for free; searchable by meaning if indexed.
VERSIONABLEdiffs, history, blame — the plan-artifact apparatus, inherited from files by birth.

Methodologies ride on the chassis

One more reason this pattern matters: it is a chassis, not a methodology. The structure — a room with a brief, a bar, work, and a result, nested — doesn't care how your domain likes to decompose. Your discipline's own scheme drops straight in:

Three methodologies, one chassis

AGILErelease/ ├── epic-onboarding/
│├── story-signup/ TASK.md =
││ the user story · CHECK.md =
││ acceptance criteria
│└── story-invite/ └── sprint-3/ …
RESEARCH GRANTproject/ ├── aim-1/
│├── study-a/ CHECK.md = the
││ preregistered analysis plan
│└── study-b/ └── aim-2/ …
SYSTEMATIC REVIEWreview/
├── search/CHECK.md = coverage
├── screening/CHECK.md = κ ≥ 0.8
│between raters ├── extraction/ └── synthesis/

Different fields, different names for the rooms, different bars on the walls. Same chassis: brief, bar, work, result, nested. The methodology chooses WHAT the tasks are; the pattern handles HOW work lives, closes, and composes.

The room inspection
  • In Example 1, the agent passed a note upward inside RESULT.md. Trace where that note should go next — whose TASK.md or CHECK.md does it want to change, and who decides?
  • What belongs in TASK.md versus the spawned agent's system message? Something must — and something must not — be in each. Draw the line and defend it.
Your turn

Take the decomposition tree you built in the earlier fork and make it physical. (1) Lay out the directories; write TASK.md and CHECK.md for the root and two leaves — the bars as runnable checks where the world can testify, critic prompts where it can't. (2) Write the RESULT.md a finished leaf should produce, evidence included. (3) Map your field's own methodology onto the chassis: what are the rooms called, and what is the bar on each wall? (4) Then the test of the pattern: hand your tree, cold, to a colleague — can they tell you what's done, what's open, and what's blocked, using nothing but ls and the documents?