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)

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

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

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