---
title: "A simple system for agent-written docs: folders, front matter and handoff files"
slug: organize-agent-written-docs-folders-front-matter-handoffs
excerpt: Good single files are not enough once your AI agents write dozens of them. Use one folder per job, date-and-topic file names, one handoff file the next session reads first, a small index across jobs, and a done folder. Copy the folder tree, index file, agent prompt and checklist.
quickAnswer: Give every job its own folder, named with the start date and a short topic. Name the files inside the same way. Keep one handoff file at the top of each job folder, and tell every new session to read it first. Keep a small index file at the root with one row per job, copied from four fields in each handoff header. When a job is finished, move its folder to a done folder. Folders tell you where things are, the header tells you where each job stands, and the handoff tells the next session what to do.
keyTakeaways:
  - One folder per job keeps every file for that job together, so the agent and you search one place.
  - Date-and-topic names sort in order and say what a file is before you open it.
  - One handoff file per job folder, read first by every new session, gives each session a written record of the job.
  - A small index with one row per job, copied from each handoff header, shows what needs you in one screen.
  - Moving finished jobs to a done folder keeps the active list short and true.
publishedDate: 2026-10-19
dateModified: 2026-10-19
author: Bobby Huang
cluster: A
role: post
status: published
faq:
  - q: Should the agent update the index, or should I?
    a: Let the agent update its own job's row at the end of each session, and check it when you read the handoff. Keep the move to the done folder for yourself, since that is the moment you agree the job is finished.
  - q: What if one job turns into two?
    a: Split the folder. Give the new job its own dated folder and handoff, add a row to the index, and put a line in each handoff that points to the other.
  - q: Do I need git for this system?
    a: No. The system is folders and plain Markdown files, so it works with or without git. If you keep the folder in git and commit your changes, you also get a history of the handoffs and the index.
related:
  - what-is-an-agent-handoff-file
  - front-matter-fields-status-date-owner
  - write-markdown-docs-your-ai-agent-can-follow
---

A single well-written Markdown file is easy to work with. Forty of them, spread across three projects and written by agents over two weeks, are not. You open the folder and can't tell which plan is current, which notes are stale, or which job is waiting on you.

This page is about the system around the files. Other guides cover the parts: how to [write a task file your agent can follow](write-markdown-docs-your-ai-agent-can-follow.md), what the [common front matter fields](front-matter-fields-status-date-owner.md) mean, and what an [agent handoff file](what-is-an-agent-handoff-file.md) holds. Here we put those parts together so a folder of agent-written docs stays readable as it grows.

The system has five pieces: one folder per job, date-and-topic names, one handoff file per job, a small index, and a done folder. Each one is small. Together they answer the three questions you ask every time you sit down: what is going on, what needs me, and where do I start.

## One folder per job

A job is one piece of work with a clear end, such as an invoice export or a dark theme for the settings page. Give each job its own folder. Every file the agent writes for that job goes inside it: the plan, the notes, the test results, the handoff.

This does two things. The agent searches one folder instead of the whole project, so it is less likely to pick up a stale plan from another job. And you can close a job by moving one folder, with nothing left behind.

Name the folder with the start date and a short topic, such as `2026-10-19-invoice-export`. The date sorts the folders in order. The topic tells you what is inside without opening it.

Keep active jobs in an `active/` folder and finished ones in `done/`. Here is a sample tree you can copy. The names are placeholders.

```text
agent-docs/
├── INDEX.md
├── active/
│   ├── 2026-10-19-invoice-export/
│   │   ├── HANDOFF.md
│   │   ├── 2026-10-19-plan.md
│   │   ├── 2026-10-20-notes.md
│   │   └── 2026-10-21-test-results.md
│   └── 2026-10-20-settings-dark-theme/
│       ├── HANDOFF.md
│       └── 2026-10-20-plan.md
└── done/
    └── 2026-10-02-csv-import-fix/
        ├── HANDOFF.md
        └── 2026-10-02-plan.md
```

## Name files by date and topic

Inside a job folder, use the same pattern: `YYYY-MM-DD-topic.md`. A file named `2026-10-21-test-results.md` tells you when it was written and what it holds. A file named `notes2-final.md` tells you neither.

Two rules keep names useful:

- **New facts get a new file.** When the agent runs tests again on a later day, it writes a new dated file rather than overwriting the old one. You keep the history, and the newest file sorts last.
- **The handoff is the one exception.** `HANDOFF.md` has no date in its name because there is only ever one per job, and the agent edits it in place. Its date lives in its header.

Don't put the date in the topic part as well, and don't add version words like "final" or "v2". The date already does that job.

## One handoff file, read first

Every job folder has exactly one `HANDOFF.md`. It is the front door to the job. It says where the work stands, what is open, and what happens next. The [guide to handoff files](what-is-an-agent-handoff-file.md) covers what goes inside, so this page only covers where it sits and how it is used.

Where it sits matters. Put it at the top of the job folder, not in a subfolder, and always under the same name. A new agent session may not carry the full context of the last one. If the handoff is always at the same path, you can tell the agent one rule that works for every job: read the handoff first.

Order matters too. The next session reads the handoff before the plan, the notes or the code. The plan says what was intended. The handoff says what actually happened and what is next. When the two disagree, the handoff wins, and the agent should say so in its open questions.

At the end of each session, the agent updates the handoff in place and keeps its headings stable. If you review handoffs from Codex, the [checklist for Codex handoff notes](review-codex-handoff-notes-checklist.md) gives you a short pass to run on each one.

## A small index across jobs

The folders and handoffs work for one job at a time. You also need a view across all of them. That is the index: one Markdown file at the root, with one row per active job.

Keep the index simple. It does not hold new information. Each row copies a few fields from that job's handoff header: status, owner, updated date and next step. The [front matter fields guide](front-matter-fields-status-date-owner.md) explains each field. If the header and the index ever disagree, the header is right and the row is stale.

Here is a sample index. The names and paths are placeholders.

```markdown
# Agent jobs

One row per active job. Each row copies the job's HANDOFF.md header.
Sorted by status: blocked first, then review, then in-progress.

| Job | Status | Owner | Updated | Next |
|---|---|---|---|---|
| [invoice-export](active/2026-10-19-invoice-export/HANDOFF.md) | blocked | Jane Doe | 2026-10-21 | Jane Doe picks the date format |
| [settings-dark-theme](active/2026-10-20-settings-dark-theme/HANDOFF.md) | in-progress | agent | 2026-10-21 | Agent wires the toggle to saved preferences |

## Recently done

- [csv-import-fix](done/2026-10-02-csv-import-fix/HANDOFF.md), closed 2026-10-04
```

Sort by status, with blocked jobs at the top. Then the first rows are the ones that need you. Keep the "Recently done" list short. Five lines is plenty; older jobs are still in the done folder if you need them.

A good reader should show each handoff's front matter as a small table, so you can check a row in the index against its header in a second. Sashmark is being built for this; the [roadmap](/roadmap) shows where it stands.

## Move finished jobs to done

When a job is finished, move its whole folder from `active/` to `done/`, and move its index row down to "Recently done". That's it. Don't delete anything.

This step keeps the system honest. If finished jobs stay in `active/`, the agent may read an old plan as current, and your index fills with rows that need nothing. A short active list is one you trust.

Keep the move for yourself. The agent can set the handoff status to `done` and say why. You read the handoff, check that it ran what it said it ran, and then move the folder. The move is your sign-off.

## How the pieces work together

Each piece answers a different question:

- **The folder** answers "where is everything for this job?"
- **The file names** answer "what is this file, and is it the newest one?"
- **The handoff header** answers "where does this job stand?"
- **The handoff body** answers "what does the next session do?"
- **The index** answers "which jobs need me today?"
- **The done folder** answers "is this still live?"

A typical sitting looks like this. Open `INDEX.md` and look at the top rows. Open the handoff for the first blocked job. Answer its open question in the handoff. Start a new agent session on that job, and it reads the handoff first. When the session ends, the agent updates the handoff and its index row. You check the row against the header next time you open the index.

This loop goes faster when the index and a few handoffs sit side by side. A good reader should open each file in its own tab and let you open a file from a terminal command, so you can go from the index to a handoff without hunting through folders. That is part of what Sashmark is being built for; see the [roadmap](/roadmap).

## Tell your agent the system

The system only works if the agent follows it every session. Paste instructions like these into your project notes or the start of each session. Change the folder name to match yours.

> This project keeps agent docs in `agent-docs/`. Each job has its own folder under `agent-docs/active/`, named with the start date and a short topic. Before you do anything, read `agent-docs/INDEX.md`, then read `HANDOFF.md` in the job folder you are working in. Name every new file `YYYY-MM-DD-topic.md` and keep it in that job folder. Never overwrite an older dated file; write a new one. At the end of the session, update `HANDOFF.md` in place, including its status, updated date and next step, and keep its headings as they are. Then update that job's row in `INDEX.md` to match the header. Do not move any folder to `done/`. I do that.

The last line is deliberate. The agent can say a job is finished. You decide it is.

## A short checklist for the system

Run through this once a week, or whenever the folder starts to feel messy:

1. Every active job has its own folder under `active/`.
2. Every job folder name starts with a date and has a short topic.
3. Every file inside follows `YYYY-MM-DD-topic.md`, except `HANDOFF.md`.
4. Every job folder has exactly one `HANDOFF.md`, at the top of the folder.
5. Every handoff header has a status, owner, updated date and next step.
6. Every active job has one row in `INDEX.md`, and each row matches its handoff header.
7. Blocked jobs sit at the top of the index.
8. No job marked `done` is still in `active/`.
9. Your agent prompt tells the agent to read the index and the handoff first.
10. Sample rows in your index use made-up names, such as Jane Doe or Doe Holdings.

If two or more items fail, fix the system before you start the next agent session. It takes a few minutes, and it saves the next session from working off a stale file.

## Where Sashmark fits

Sashmark is a Markdown reader and editor for people whose AI agents write Markdown. It is in development and has not been released, and the app itself has no AI features. It is being built for the reading half of this system: checking headers, moving between files and seeing what changed. See the [planned features](/features), the [help pages](/help) and the [roadmap](/roadmap) for where each part stands.

Sashmark is in development. See what it is at [sashmark.com](https://www.sashmark.com/).