rzen
88364b20c0
Rulings written in place: the drop settle yields to the system drag session (fly-to-slot deferred to WISHLIST #7) and the held proposal's home is the app-wide DragSession — rendering the arrangement means rendering the card at release (03, 02); folder drops refuse at hover with loss-row reporting, created cards land positionally, N shadows, header resolves topmost, shadow-only feedback (04); the banner vocabulary gains the warning-tone loss row class (02); all user-initiated creation clears the search (04); loose files beside a card's index.md relocate into attachments/ with notice — files-only carve-out, paste normalizes at the boundary, the agent guide teaches it (01, 04, 08); dropping a card on the shown trash deletes it, shadow pinned topmost (04); query-emptied lanes keep their slot, the out-transition stays reachable, an open rename survives the filter, pasteboard staleness accepted (04). The face carousel does not carry over: the pathfinder's selection-keyed dual presentation proved undesirable — one presentation per card, selection changes styling never geometry; the attachment chip and the card window are the whole media story (03, 01, 10, 11; the same-day carousel settlements superseded on their Resolved cards). Claude-Session: https://claude.ai/code/session_01CqjXB7ASoWtbyoGod68k97
50 lines
6.5 KiB
Markdown
50 lines
6.5 KiB
Markdown
# 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).
|
|
- Tombstone deletes, colors/icons.
|
|
- New in the rewrite: **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.
|
|
- New in the rewrite: **`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.
|
|
- 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 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).
|