lanework/DESIGN/08-agent-integration.md

Agent Integration

AI agents are first-class users of Lanework boards — not through an API, but through the filesystem itself. An agent that can read and write files can read and write a board. The app's design carries several load-bearing guarantees that exist substantially for this use case.

The load-bearing guarantees

1. Unknown-key preservation — agent overlays add custom frontmatter (project:, sphere:, tags:) and the app preserves hand-added keys and their order verbatim across every rewrite. The schema is safe to extend from outside.
2. Live external-edit reload — an agent writing a card folder makes the card appear on the open board via FSEvents immediately. Agent write-path and human read-path are the same surface; the agent is just another external editor.
3. Fail-fast validation + atomic writes — a malformed agent write surfaces loudly with the offending path instead of silently corrupting. The right failure mode for letting AI write into a planning system.
4. Skip-don't-fail for index-less folders — an agent interrupted between mkdir and writing index.md cannot brick the board.
5. Git trail (06-history-undo.md) — on git-enabled boards, agent changes are auto-committed, attributed, and undoable like any others. Foreign changes are committed under a synthetic external author, structurally distinct from the user's own commits; an agent can claim its work lightly by stamping modified-by (guarantee 6 below), or precisely by committing its changes itself — the app follows along: a held index.lock just makes the auto-committer retry/re-debounce, and a tree the agent already committed is a silent no-op that preserves the agent's authorship (06-history-undo.md). The guide says so, and also tells agents to stage only their own paths (no git add -A) — a sweep would commit the user's not-yet-auto-committed changes under the agent's name.
6. modified-by self-stamping (01-storage-format.md) — the lightweight attribution path: an agent stamps files it writes (modified-by: <your-name>), and the stamp renders on the card window's modified line and authors the agent's foreign commits (06-history-undo.md) — no git ceremony, and it works on no-git boards, where it is the only attribution there is. The app clears the stamp on its own writes, so agents should re-stamp on every write, not once.

The agent guide (CLAUDE.md at board root)

The app silently maintains a CLAUDE.md in every board — a condensed, agent-facing rendition of the schema teaching any agent how to operate on the board directly:

• Creating cards (mkdir UUID, write index.md, ordering rules).
• Moving between lanes (folder move), reordering (gapped ranks, only touch the moved item).
• Tombstone deletes, colors/icons.
• New in the rewrite: attachments (the attachments/ convention, importing files).
• New in the rewrite: modified-by self-stamping — stamp files you write; re-stamp every write (the app clears it on its own writes); self-commit instead when you need exact authorship.
• New in the rewrite: a pointer to the optional CLAUDE.user.md (see below), instructing agents to read it when present.

Mechanics: version marker in the first line (lanework-agent-guide vN); rewritten when missing or older, never downgraded, left untouched when current or newer. To the loader it's just another ignored file.

Ownership: the board-root CLAUDE.md is app-owned and not available for user editing — its header says so, and user edits do not survive upgrades. This holds on every board, including repo-nested ones: the guide is auto-written there too (the untracked file in the user's repository is accepted — a board is agent-facing wherever it lives). A board-root CLAUDE.md found without the marker is displaced user content, not clobbered: its content is moved to CLAUDE.user.md if that name is free (otherwise the guide write is skipped with a log — user content is never destroyed), and the guide is then written.

CLAUDE.user.md is the user's extension point: an optional, user-authored file at board root carrying board-specific agent instructions. The generated guide tells agents to read it when present, so it lands in agent context without the app ever touching it — the app never writes, upgrades, or validates it.

On git boards, a guide write rides the normal watcher → auto-commit path with an honest message ("Update agent guide (v3)"), not "External edit" (06-history-undo.md).

Agent conventions worth specifying (new in the rewrite)

• The masterplan pattern (from the old repo's AI-MASTERPLAN.md): a cross-project board with lifecycle lanes (Inbox → Triaged → Active → Done) where agent sessions file needs as cards at near-zero friction. The design requirement it imposes here: filing a card must need nothing but the schema — no app running, no registration, no index to update.

Automation surfaces (beyond raw files)

Raw files are the primary surface. Candidates for more, all unadjudicated:

• CLI (lanework add-card …) — probably unnecessary; agents handle raw files fine, and a CLI is a second schema client to maintain.
• URL scheme / AppleScript / Shortcuts — for human automation more than agents.
• MCP server — same schema knowledge packaged for non-file-capable agents.

Lean: ship none initially; the guide + schema are the API.

Open questions

None currently — the "while you were away" digest idea moved to the project wishlist (../WISHLIST.md).