Anatomy of a Lanework board
Right-click a Lanework board in Finder and choose Show Package Contents. What you see is not an export of the board, or a cache of it, or a backup. It is the board. There is nothing else.
This post is a tour of that folder. I’ll go through what’s in it, piece by piece, and explain why each piece is the way it is. Some of the choices look strange the first time you meet them. Folders named with long strings of hex, for one. Every one of them was an argument I had with myself, and I’d like to show the working.
The one idea
Everything else follows from a single decision: the files are the board.
Lanework has no database behind the folder. The app is a live view over the files. It watches the folder, and when anything in it changes, the board on screen changes too. It doesn’t matter who made the change. A drag in the app and an mv in a terminal are the same event.
That means there is no API, and no import or export. Anything that can write a file can work a board: a text editor, a shell script, a Shortcut, an AI agent. None of them needs permission from the app, and none of them needs the app to be running.
I wanted this for two reasons. The first is ownership. A board should still make sense in twenty years, on a machine that has never heard of Lanework. Plain folders and Markdown will. The second is agents. A coding agent already knows how to read and write files, and that is all it has to know.
So the format had a hard job. It couldn’t be the app’s private storage that happens to be readable. It had to be the interface.
The tree
Here is a whole board:
Website.lanework/
├── index.md the board
├── 3f2a9c41-•-7d52/ a lane
│ ├── index.md
│ ├── 27ca60f1-•-e066/ a card
│ │ ├── index.md
│ │ ├── attachments/
│ │ └── comments/
│ └── 8d3b1f22-•-a9c4/ another card
│ └── index.md
└── b1e4d7a0-•-14be/ another lane
└── index.md
Every level is the same shape: a folder with an index.md inside it. The board is a folder. A lane is a folder in the board. A card is a folder in a lane.
Depth is the type. A folder one level down is a lane, and a folder two levels down is a card. Nothing in the file says “I am a card” in a way the board depends on.
I did this because a type field is a second copy of a fact the filesystem already holds, and two copies can disagree. If position is the only truth, then moving a card to another lane is one folder move. Nothing has to be updated to match. The folder move is the move.
Names are identities, not titles
The folder names are the part people wince at. A card called “Fix the login crash” lives in a folder called something like 27ca60f1-ef07-44d5-b688-73bf1f77e066. The title is inside, in the file.
The obvious alternative is to name the folder after the card. It doesn’t hold up. Titles change, and a folder named after a title has to be renamed with it, which breaks every link and every reference that pointed at the old name. Titles collide: two cards called “Notes” can’t share a lane. And titles contain slashes, colons and emoji that filesystems treat in their own ways.
A UUID has none of those problems. It never changes, so a link to a card survives every rename and every move. Two cards can never collide, so two people (or two agents) can each file a card at the same moment without knowing about each other. And in git, a retitled card is a one-line change, not a deleted folder and a new one.
One rule falls out of this. A move keeps the name, and a copy gets a new one. A card dragged to another lane, or to another board, is still the same card. A duplicate is a new card that happens to start with the same content.
The cost is real: you can’t browse a board in Finder by eye. I decided that was the right cost to pay. Finder shows a board as one document, the app is the comfortable way to look at it, and grep finds anything by title in a moment.
There’s a small kindness hidden in here. The app writes lowercase UUIDs, but it accepts any case. On a Mac, uuidgen prints uppercase, and so does Swift. A strict rule would have meant that a card made with the standard tool was silently ignored, which is the worst thing a files-first app can do to you.
Inside index.md
An index.md is YAML frontmatter, then a Markdown body. Here is a card:
---
schema: 1
kind: card
title: "Fix the login crash"
order: 3072
created:
{ at: 2026-11-02T18:00:00Z, by: { name: claude, kind: agent, model: opus } }
modified:
{ at: 2026-11-03T09:12:04Z, by: { name: claude, kind: agent, model: opus } }
---
Tapping Sign In twice crashes the app on a slow connection.
The body is the card’s content, in any Markdown you like. The frontmatter is everything the board needs to know about it.
Almost all of it is optional. The smallest legal card is this:
---
title: "Fix the login crash"
---
One folder, one file, one line that matters. That was a requirement I held onto the whole way through: filing a card should need nothing but the format. You shouldn’t have to read the rest of the lane, or ask the app for a number, or know what version anything is.
Order without renumbering
A lane’s cards run top to bottom by order, lowest first. The numbers have gaps on purpose. A new card at the bottom takes the highest number plus 1024. A card dropped between two others takes the number halfway between them.
The point is that a reorder rewrites one file. The card you moved gets a new number, and no other card is touched. Compare that with numbering cards 1, 2, 3, where moving one card to the top rewrites every card below it. On a board in git that’s the difference between a one-line diff and forty. On a board two people are editing, it’s the difference between no conflict and a mess.
Eventually two neighbours get so close that there’s no room between them. Then that one lane is renumbered, back to clean multiples of 1024. It’s rare, and it stays inside the lane.
And if a card has no order at all? It goes last. That’s what makes the three-line card above legal. An agent filing into a lane of two hundred cards doesn’t have to read two hundred files to find the bottom.
Who did what
created and modified aren’t bare timestamps. Each one says when and who. The who has a name, whether it’s a human or an agent, and for an agent, which model.
This matters because a board has more than one pair of hands on it. I move cards. Agents file them, comment on them and move them along. When I look at a card that changed overnight, the first thing I want to know is who changed it.
One rule here surprises people. A stamp with no by means the owner did it. It doesn’t mean “unknown”. The app leaves by off its own writes, because those are the writes of the person sitting at the Mac. So an agent that forgets to sign its work isn’t anonymous. It’s claiming to be me. The rule is strict so that the absence of a name can be trusted as much as a name.
A second rule keeps modified honest. Moving a card to another lane stamps it, because that’s a change to the card’s story. Reordering it within a lane doesn’t, because nothing about the card changed. The same goes for the app’s own housekeeping. When the app repairs an old spelling in a file, it leaves modified alone. Otherwise every repaired card would jump to the top of “recently modified”, and the board would be reporting a change nobody made.
Labels carry their whole meaning
A label on a card looks heavier than you’d expect:
labels:
[
{
text: High,
rank: 1,
color: "#E07A1F",
kind: { type: priority, text: Priority },
},
]
The usual design would store priority: high on the card and keep the meaning of “high” in the board’s settings: its colour, its place in the scale. Lanework stores the answer on the card. The colour, the rank and the kind are all written out, on every card that carries the label.
That is redundant, and the redundancy is deliberate. A card is a file, and files get copied. Drop a card into another board, or mail it to someone, and it still means what it meant, with no settings file needed at either end.
The board does have a list of label kinds, and that’s where the pickers in the app get their choices. But I think of it as a palette to write from, never an authority to read from. Nothing that draws, sorts, filters or groups a card ever looks a label up. Recolouring “High” in the board’s settings changes the next label you apply. Every card already written keeps saying exactly what it said.
Deleting is moving
Delete a card and its folder moves into .trash/ at the top of the board. That’s all.
An earlier design marked a deleted card with a deleted: key and left it where it was. It didn’t last. Every reader had to remember to check the flag, and a deleted lane meant hiding cards because of something their parent said. A folder move has none of that. A card in the trash is plainly in the trash, to the app, to ls, and to anyone reading a diff.
Restore is the same move in reverse, with no special machinery. And the trash needs no ordering of its own. The move stamps modified, and the trash sorts by that, newest first.
This is the one place the optional kind key earns its keep. On the live board, depth tells a lane from a card. The trash is flat, and an empty lane looks exactly like a card. So kind: lane is what tells them apart in there.
The same shape, all the way down
Attachments and comments follow the pattern you already know. Each one is a UUID-named folder with an index.md.
An attachment’s file is always called blob, plus its extension. The name a person sees lives in the attachment’s index.md. So renaming an attachment never breaks a reference to it, which is the folder-name idea again, one level down. A card body points at an image with an ordinary relative path, so the picture renders in any Markdown viewer, not only in Lanework.
A comment is a small Markdown file with a created stamp. The stamp is its position, so the thread sorts by time and needs no numbering. The split between the two is deliberate. The card’s body is the spec, and the thread is the journal: what was decided, what was tried, what’s being asked. When an agent picks a card up cold, the thread is how it catches up.
Lenient, and never lossy
A format that anyone can write by hand will be written wrongly. How the app reacts to that is as much a part of the format as the keys.
The rule I settled on: recover whatever can be recovered reliably, and never accept a loss that would surprise you. In practice every problem the app can detect gets one of five answers.
- Tolerate. A stray file, a
notes/folder, a symlink: left exactly as found, and not drawn. Nothing odd in a board folder can stop it loading. - Coerce. A bare timestamp where a full stamp belongs is read as the stamp. The file’s bytes stay as you wrote them.
- Heal. Where there’s one right repair and it loses nothing, the app makes it. A missing
kindgets filled in the next time that file is written anyway. - Refuse writes. A few shapes can be read safely but not edited safely. The card shows, and an edit fails with a clear message.
- Refuse. Frontmatter that won’t parse stops the load. The app won’t guess at what you meant. It names the file and the problem, and offers to open it, fix it or skip it.
Two promises sit under all of this. Keys the app doesn’t know are kept exactly as written, so your own metadata (project:, sprint:, anything) is safe to add and survives every rewrite. And the app never reformats what it didn’t change. Edit a title, and one line of the file changes. The body, the line endings and the order of the keys come back byte for byte.
A board that explains itself
If files are the interface, the manual has to travel with them. So every board carries its own.
At the top of the board sit CLAUDE.md and AGENTS.md, two copies of one guide that the app writes and keeps current. It’s the whole format, written for a reader who is about to edit a file. Beside it is .schema/, the same rules as JSON Schema, generated from the app’s own reading code so the two can’t drift. A small validator script sits in there too, and it runs on the Python your Mac already has.
The result is that an agent arriving at a board it has never seen needs nothing installed. The instructions, the schema and the checker are in the folder it was pointed at.
There’s room for your rules as well. The board’s own index.md body is its description, and anything below the first heading is your instruction sheet: what “done” means here, what an agent may touch. Each lane’s body does the same for that lane. The app’s guide says how the format works. Yours says how this board works.
Good in git, without git
Lanework never runs git. It makes no commits and never looks inside .git.
But the format was shaped to sit well in a repository. One file per card. Folder names that never change. Rewrites that touch only what changed. Put a board in a repo and the history reads like the work: a card moved, a title changed, a comment added, each a small diff you can follow.
I like that the app doesn’t have to know. Version control is your choice, made with your tools, and the board is no different for it.
What it adds up to
Looking back, the same few ideas kept deciding things:
- The files are the board. There’s no second copy anywhere to fall out of step.
- State each fact once. Position says what a thing is. The folder name says which thing it is.
- Make every change small. One gesture, one file, as few lines as possible.
- Let each file stand alone. A card should mean the same thing wherever it’s copied.
- Keep what you don’t understand. Unknown keys and odd files are preserved, never tidied away.
- Never lose anything quietly. Recover what’s safe to recover, and say so plainly when you can’t.
- Ship the manual in the folder. Whoever opens a board next, person or program, should find what they need right there.
None of these is clever by itself. What I’ve come to appreciate is how they hold each other up. Stable names make small diffs possible. Small diffs make shared boards calm. Cards that stand alone make copying safe. And a format this plain can be handed to an agent with nothing but a folder path.
That’s the whole anatomy. If you have a board, go and look inside it. It’s all yours.