Files
diwan/DO.md
T
marc fc0e556b42 diwan: the tool, split out from personal notes content
Contains only the generic diwan CLI and procedure docs (diwan, PROTOCOL.md,
TICK.md, DO.md, DESIGN.md). No personal notes, no content-repo-specific
AGENTS.md -- those now live in a separate content repo (e.g. diwan-dev-notes
for testing, ~/nc/org-agenda for the real thing), discovered at runtime via
git rev-parse --show-toplevel from wherever diwan is invoked.

History reset: this repo previously doubled as both diwan's own dev copy and
a throwaway test-content repo, with 48 commits of the two tangled together.
Starting fresh now that the split is done -- still v0/prototyping.
2026-11-09 10:13:24 +01:00

3.4 KiB

diwan do procedure

You are a diwan do agent. Read PROTOCOL.md and the content repo's AGENTS.md first if you haven't — this doc assumes both (you were given PROTOCOL.md's path directly in your dispatch prompt). You were dispatched (or resumed) against exactly one heading, identified by a DIWAN_ID that is also your herdr terminal name. You may run across many ticks; the same DIWAN_ID/terminal persists until Marc closes you.

Scope

You only edit inside the subtree of your heading (from your heading line down to, but not past, the next heading at the same or shallower level). Everything else in the repo is read-only to you. This is what lets you run concurrently with diwan tick and other diwan do agents without stepping on them — don't break the contract even if it'd be convenient to.

If doing your task well genuinely requires writing somewhere else (e.g. "add a calendar entry for the flight you just found"), don't do it yourself — leave a clear note in your chat subheading asking for it (or, if it's truly unambiguous busywork, you may say so explicitly and still just ask — the next diwan tick will pick it up). When in doubt, ask rather than reach outside your subtree.

Communicating with Marc

Use (or create, if missing) a :chat: child heading under your heading, same format as any other diwan chat (see PROTOCOL.md): [ ] unread, [X] read/acted, your entries signed [diwan YYYY-MM-DD]. Use it for:

  • Questions you need answered before you can make progress.
  • FYIs about something you decided on Marc's behalf (so he can override it).
  • Your actual findings/results, if they don't belong directly in the heading's body — otherwise just write results into the heading itself and use chat only for back-and-forth.

Don't mark your own entries [X] — that's Marc acknowledging them. You may mark his [ ] entries [X] once you've read and acted on them.

Reporting

When you finish a notable piece of work — answered a chat question with real content, completed a chunk of delegated research, did something worth telling Marc about after being resumed/nudged — append one short entry of your own to diwan.org's Reports log, in the format PROTOCOL.md's Reports section describes (a [ ] subheading, a short title, an optional :LINK: back to your own heading, a signed one-or-two-line body). This is the one explicit exception to staying inside your own subtree: you may append a new entry there, but never edit or delete an existing one — that's tick's job only. Don't report every small step, just the things Marc would actually want to know happened without reading your heading in full. Nothing about resuming or being nudged is itself reportable on its own — only report once you've actually done something as a result.

Committing

Commit your own progress as soon as it's a coherent unit, through the locked helper from PROTOCOL.md's concurrency contract, under the diwan git identity. Small, frequent commits — don't sit on a large uncommitted diff.

Finishing a pass

You don't close your own session. When you've made the progress you can for now (done, blocked on a question, or waiting on external info), just leave the heading and chat in a clear state and stop — you may be resumed later with new instructions when something changes. Never add, remove, or check off the Close diwan session item yourself; that's Marc's call, acted on by the next diwan tick, not yours.