Folder layout and tools
A board is a folder named Something.lanework. Inside it, lanes are folders, cards are folders inside lanes, and everything is plain Markdown. The Lanework app shows the files live, and there is nothing to sync or call: the files are the board.
<board>/├── index.md board title and settings; body is the description, then agent instructions below its first ##├── CLAUDE.md the agent guide (app-maintained)├── AGENTS.md identical copy of CLAUDE.md (app-maintained)├── .trash/ deleted cards and lanes (app-managed)├── .log/ the activity log, one file per UTC day (app-managed)├── .schema/ the board's JSON Schema and tools (app-managed)│ ├── bin/lanework-validate.py│ ├── bin/lanework-heal.py│ └── HEAL.md├── <uuid>/ a lane│ ├── index.md lane title and order; body is notes and policy│ ├── <uuid>/ a card│ │ ├── index.md card title and order; body is the card's content│ │ ├── attachments/ one uuid folder per file│ │ └── comments/ the card's comment thread│ └── <uuid>/ another card└── <uuid>/ another laneDepth alone gives meaning: a folder at depth 1 is a lane, and one at depth 2 is a card. Folder names are lowercase UUIDs and are permanent, so never rename one. Titles live in frontmatter only.
Every index.md is YAML frontmatter between --- lines, then a Markdown body. Files are UTF-8 with no byte order mark. Keep each file’s existing line endings, and end new files with a line feed.
See Board, Lane, Card, Comment and Attachment for the files.
Files the app owns
Section titled “Files the app owns”The app writes and updates these. Do not edit them by hand.
CLAUDE.mdandAGENTS.md: the agent guide, kept identical and rewritten on upgrades. Board-specific instructions go in the board’s ownindex.md, below its first##heading..schema/: the JSON Schema files, the validator, the repair script and the repair catalogHEAL.md. It is rewritten when the app ships a newer version..gitignore: seeded by the app and rewritten each time the board opens..log/: the activity log. Read-only: never append to, edit or commit it..trash/: deleted cards and lanes, described next.
Deleting
Section titled “Deleting”To delete a card or a lane, move its folder into <board>/.trash/, creating .trash/ if it is missing. A lane takes its cards with it. Move one folder at a time, by name, never with a glob such as mv <laneA>/* <laneB>/, which would also sweep up a lane’s own index.md.
Moving into .trash/ is a change like any other move, so restamp modified with both at and by. The trash is sorted by modified.at, newest first. Leave order as it is, because it is used if the item is restored.
When you trash a lane that has no kind key, add kind: lane. The trash is flat, so that key is what tells an empty lane from a card.
To restore, move the folder back and give it a fresh order, stamped the same way. Delete a folder outright with rm -r only when you mean it to be permanent.
The validator
Section titled “The validator”python3 .schema/bin/lanework-validate.py <path>The path can be one index.md, which is checked alone against the schema for its position, or a whole board, which is walked including .trash/ but not comments/.draft. It needs nothing installed.
- A failing document prints one line naming the rule that failed, and the run exits
1. - A
DEPRECATEDline names a retired form a value matched. The run still exits0. - A
WARNline reports something suspect, such as aheroorin-reply-tothat matches nothing. It prints and fails nothing. - A clean file prints nothing. A board walk always ends with a summary of what it found.
Exit 0 with no DEPRECATED line is the check to make before you commit a file you wrote by hand.
The repair script
Section titled “The repair script”python3 .schema/bin/lanework-heal.py <board>python3 .schema/bin/lanework-heal.py <board> --apply --name <you> --model <model>The first command is a dry run: it prints one line per repair the board needs and writes nothing. A line reads <file>: <rule id> <code> <what>. A line starting with skip is something the script leaves for you to fix by hand.
Add --apply to make the repairs. Pass --name and --model so the repair is signed as you. Use --session <s> to record a session id. Then run the validator on what changed.
The script repairs old spellings and damaged labels. .schema/HEAL.md lists every repair under a rule id with a before and after.
What every repair keeps to:
- It never changes
modified, and never touchescreated. A repair is upkeep, not an edit. - It never adds a missing
by. - If a repair would remove something a person wrote, it first posts a comment on the card quoting it. The comment is signed with the name you gave. Never sign as
healerorshortcuts. - It leaves unknown keys alone and never walks
.trash/,comments/.draftorcomments/.trash. - A file no rule changes is not rewritten, and a second
--applystraight after finds nothing to do.
Two rules, H13 and H14, re-apply the board’s label definitions to existing cards. Run them only when the board’s owner asks, and read the dry run first.
Keeping a board in git
Section titled “Keeping a board in git”Lanework never runs git. But the format suits it: one file per card, stable folder names, and byte-faithful rewrites. A board can live inside a repository of your own.
- Stage only your own paths. Avoid
git add -Aandgit add ., which would commit someone else’s unfinished changes under your name. - Commit with clear messages, such as “Move card ‘Fix login’ to Doing”.
- Leave the app-maintained files to the app, including
CLAUDE.md,AGENTS.mdand.gitignore. Do not commit changes to other people’s files. - Commit
.schema/along with the board. - Do not put your own exclusions in the board’s
.gitignore: the app rewrites it every time the board opens. A board is never a repository root, so put your rules in a.gitignoreabove the board’s folder.