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 — and on every move: a bare folder move rewrites nothing, so the moved card arrives unstamped and the commit falls back to the generic external author (06's fallback demotes on unstamped changed files and true deletions; a move is neither stamped nor a deletion until the agent re-stamps it).

The agent guide (CLAUDE.md at board root, twinned at AGENTS.md)

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) — plain UTF-8, no BOM, preserving each file's existing line endings (01-storage-format.md's encoding contract).
• Moving between lanes (folder move), reordering (gapped ranks, only touch the moved item).
• Deletes — move the card or lane folder into <root>/.trash/ and restamp modified (the trash sorts newest-first by that stamp — re-ruled 2026-07-31, no rank to mint; never delete a folder outright unless permanence is meant); colors/icons.
• kind — common schema, written at creation of every object: include kind: lane / kind: card when creating anything (kind: board at board root), and stamp kind: lane when trashing a lane that lacks it. The value is what tells a trashed lane from a card inside the flat .trash/ (01-storage-format.md ▸ Deletion); the app backfills a missing key on touch (01 ▸ Validation and healing), so omitting it is healable, never fatal.
• Attachments (the attachments/ convention, importing files) — including the rule that card files belong in attachments/: a loose file written beside index.md will be relocated there by the app with a notice (01-storage-format.md's loose-file carve-out), so agents should put it there in the first place — and the card-level attachments claimed name: attachments inside a card folder is the app's (the card's file folder); never create a file by that name.
• modified-by self-stamping — stamp files you write; re-stamp every write and every move (the app clears it on its own writes; a bare folder move leaves the card unstamped); self-commit instead when you need exact authorship.
• The stamp discipline of 01 ▸ modified's scope: reordering within a lane rewrites only order — leave modified and modified-by alone — while a move between lanes, between boards, or into/out of .trash/ updates both (stamp modified, re-stamp modified-by).
• Comments (comments/ — 01-storage-format.md § Enhanced schema, shipped 2026-07-29): the folder shape (comments/<uuid>/index.md, no title/order), chronology as the ordering (sorts by created ascending — write real current UTC, distinct seconds for a burst), author as self-reported content that survives app writes (the deliberate contrast with modified-by, which the app clears), comments/.draft and comments/.trash as reserved names one level down the agent never writes into, and retraction by a follow-up comment rather than a rewrite. comments/ no longer appears on the reserved-tracker-keys list below — it shipped, and the list now names only the fields tracker sync still reserves (labels, assignees, due, remote, remote-state).
• Use the thread: journal your work (added with the comments chapter, ruled 2026-08-09, card dc1314bb): the card's body is the spec, its comment thread is the journal. Starting a card gets a comment with the plan and every decision already made, written for a reader with none of the session's context; decisions get recorded as they're made, not reconstructed at the end; questions post as comments, since the app narrates arrivals live and a thread has to be re-read in full before a card is resumed; finishing gets a comment with verification evidence. Posting a comment never stamps the card's own modified/modified-by. Per-board process — lane cadence, commit conventions — stays CLAUDE.user.md's, not the guide's.
• A pointer to the optional CLAUDE.user.md (see below), instructing agents to read it when present.

This list is present-tense and normative for the current guide (re-ruled 2026-07-30): it states what the shipped guide teaches now, and editing it means editing the guide literal in the same change. Per-version changelog bullets are deliberately gone — a hand-maintained version history beside the literal drifted within days of v6 (claiming teachings the shipped body lacked), the same failure class as README's hand-enumerated deferred list; version history lives in git.

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.

The AGENTS.md twin (ruled 2026-08-09, card dc1314bb): the app writes the identical guide a second time, at AGENTS.md — the vendor-neutral filename most non-Claude coding agents read, alongside CLAUDE.md for Claude's own pickup. Same lifecycle as CLAUDE.md in every particular — seeded at board creation, rewritten on a version bump, left untouched when current, a markerless file on the name rescued and a squatter displaced exactly as CLAUDE.md's own are — because each name gets the identical decision run against it independently, not a copy of the other's outcome. A duplicate, deliberately not a symlink: iCloud Drive's symlink handling is unreliable, and the two files are written from the one generator on every install, which makes drift structurally impossible rather than a discipline someone has to maintain. Both names join the claimed board-root list the Git section already tells agents to leave to the app.

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 an existing CLAUDE.user.md; the one exception is its creation, once, to rescue displaced content (the markerless-CLAUDE.md relocation above, which only runs when the name is free — and which AGENTS.md shares: a markerless file on either claimed name rescues to this same single destination, never a second AGENTS.user.md).

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 ▸ Commit messages — the non-snapshot-files rule: the committer stages the whole root, and the composer reads the subject's version from the guide's marker line, a pure function of file content).

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