lanework/DESIGN/00-vision.md

Vision

What Lanework is

A native macOS kanban app whose storage is plain folders + Markdown files. Every board, lane, and card is a folder containing an index.md (YAML frontmatter + Markdown body). The filesystem is the source of truth; the app is a live view over it.

The defining consequence: anything that can read and write files is a first-class user of a board — text editors, Finder, shell scripts, git, and above all AI agents. Claude Code working in a repo can file, move, and annotate cards with zero API, zero sync machinery, zero app-specific tooling. The app's job is to be the best human surface over that substrate.

Who it's for

• Individuals and small teams who want their planning data in files they own — greppable, diffable, versionable, portable.
• Developers who live in git and want boards to ride along with (or next to) their repos.
• People working with AI agents, who want the agent and the human looking at the same board through their respective native surfaces (files for the agent, a polished Mac app for the human).

Design principles

1. Files first. Every feature must degrade gracefully to "it's just folders of Markdown." If the app vanishes, the data remains fully usable.
2. The app never surprises the file. Unknown frontmatter keys survive verbatim; untouched bodies are never rewritten; writes are atomic. Hand edits and app edits coexist without ceremony.
3. Fail fast on malformed input. A broken file surfaces a loud, specific error with the offending path — never partial loads, never data loss by "repair," never a rewrite of anyone's bytes. The one scoped softening is 01-storage-format.md's read-side rescue family (duplicate-key last-wins, the unquoted-colon recovery): an obvious hand-editor slip reads as what the writer meant — silently, with a log line, bytes preserved verbatim — because bricking a board over a recoverable slip fails files-first harder than leniency does. Fail-fast keeps guarding structure the rescues can't legitimize.
4. Native to the bone. SwiftUI, macOS conventions (Finder-style rename, ⌥-drag copy, package documents, real windows), no web tech, no JS runtime.
5. Agents are users, not integrations. The schema, the agent guide, and the tolerance rules are designed for programmatic writers from day one.

Editions

Lanework ships as three editions from one codebase and one format (12-editions.md): Lanework (no git; macOS-native undo — 13-native-undo.md), Lanework Pro (git-backed history, branches, remote sync — 06/07), and Lanework Teams (Pro plus tracker integration over the reserved enhanced schema; deferred). Separate Mac App Store apps sharing the .kanban UTI — any board opens in any edition. The deeper reason for the split: history and sync live behind a provider seam, so Teams' sync can be backend-agnostic (git and trackers) instead of git being load-bearing everywhere.

App identity

The previous version was a pathfinder — it never shipped. This rewrite is the app. It keeps the internal codename Kanban (Xcode target, scheme, bundle id dev.rzen.indie.Kanban) and ships under the display name Lanework. Because nothing shipped, there is no migration story and no compatibility obligation to pathfinder boards; the schema number stays 1, redefined by this design (see 01-storage-format.md).

Goals for the rewrite

• Preserve the on-disk philosophy and the interaction quality of the pathfinder while restructuring the schema and codebase with what we learned.
• Promote attachments to a first-class schema citizen.
• Split the schema into a core schema (this version: boards, lanes, cards, attachments) and an enhanced schema (comments, tracker fields) that is reserved but out of scope — see 01-storage-format.md.
• Build the collab integration axis (local-only / git) into the design from the start instead of retrofitting it.
• Keep the codebase honest about its layering: storage contract → store → views, with the cache rebuildable and the flow one-way.
• Keyboard navigation as first-class UX — the board fully operable without the mouse (04-interactions.md).
• Accessibility is a requirement of "native to the bone," not an afterthought. The keyboard-first contract doubles as the drag-free operation guarantee — that's the floor. VoiceOver correctness on the custom board, text scaling, and the system visual accommodations are designed in 10-accessibility.md.

Non-goals

• No web or iOS version (design shouldn't preclude iOS forever, but nothing is compromised for it now).
• No MDX, no embedded scripting, no plugin runtime.
• No wiki-style cross-linking between cards (considered and punted — overkill for kanban).
• No tracker integrations (Gitea/GitHub/GitLab/Jira boards) in this scope — the schema reserves remote/remote-state so a future connector isn't foreclosed, but nothing here is designed for them.
• No comments functionality in this version — comments/ is reserved in the enhanced schema for future integrations.
• No server. Sync rides on git remotes — never on infrastructure we run.
• No iCloud Drive boards. The app warns against placing a board in iCloud Drive (thorough explanation, git recommended instead) and makes no iCloud accommodations — see 07-sync-collab.md.

Open questions

None currently — identity and migration are settled (see App identity above).