The Task Is a Directory

From tree to filesystem

The decomposition tree we just built was a diagram. Now meet the most common way real systems make it physical — a pattern so natural it feels obvious the moment you see it, and so powerful it carries most serious agent projects today: give every task a directory.

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

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:

⟨tool_use⟩
read_file(path = "TASK.md")

⟨tool_result⟩
[the brief: format quirks, the A2-v1 interface pointer, scope]

⟨tool_use⟩
read_file(path = "CHECK.md")

⟨tool_result⟩
[the bar: conformance on 3 samples, UTC/meters, no silent drops]

⟨tool_use⟩
write_file(path = "work/parse.py", content = "[the adapter]")

⟨tool_use⟩
run_command(cmd = "./check.sh")

⟨tool_result⟩
FAIL: sample-3: 2 rows dropped without log entries (trailing
summary rows discarded silently).

⟨tool_use⟩
write_file(path = "work/parse.py", content = "[logs rejected
rows explicitly]")

⟨tool_use⟩
run_command(cmd = "./check.sh")

⟨tool_result⟩
PASS: 3/3 samples · 4,112 rows · UTC/meters confirmed ·
rejects logged (2). Log: work/sample-runs/run-9.log

⟨tool_use⟩
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.")

The hierarchy is the visibility

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

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:

"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.

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: