Skip to content

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 lane

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

The app writes and updates these. Do not edit them by hand.

  • CLAUDE.md and AGENTS.md: the agent guide, kept identical and rewritten on upgrades. Board-specific instructions go in the board’s own index.md, below its first ## heading.
  • .schema/: the JSON Schema files, the validator, the repair script and the repair catalog HEAL.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.

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.

Terminal window
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 DEPRECATED line names a retired form a value matched. The run still exits 0.
  • A WARN line reports something suspect, such as a hero or in-reply-to that 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.

Terminal window
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 touches created. 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 healer or shortcuts.
  • It leaves unknown keys alone and never walks .trash/, comments/.draft or comments/.trash.
  • A file no rule changes is not rewritten, and a second --apply straight 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.

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 -A and git 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.md and .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 .gitignore above the board’s folder.