rzen
b0763c3c82
Twelve design docs (00-vision through 11-command-nexus) plus assets and the wishlist, authored ahead of implementation. Claude-Session: https://claude.ai/code/session_018BjQRYBR6jQja3jCRi5S3A
50 lines
5.4 KiB
Markdown
50 lines
5.4 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.
|
|
|
|
## 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).
|