Files
diwan/DO.md
T
marc 34f1f4396e Close diwan session: TODO/DONE instead of checkbox; purge evolutionary residue from all docs
1. 'Close diwan session' now uses TODO/DONE (assign_diwan_id inserts
'** TODO Close diwan session'), matching Reports. No headline anywhere
in diwan's own docs uses a [ ]/[X] checkbox now -- only :chat: list
items do, which is correct org usage (checklist items, not headline
states) and unaffected.

2. Rewrote PROTOCOL.md/TICK.md/DO.md/DESIGN.md to read as a single
coherent design rather than a changelog of how they got here. Removed:
contrastive 'not because X, but because Y' phrasing that only makes
sense if you know the prior rule, references to old tag names/formats
that no longer exist, a Claude-Code-vs-pi rationale that belongs in
DESIGN.md (if anywhere) not the agent-facing PROTOCOL.md, and 'no
:LINK: property' (never describe a convention by naming something it
doesn't have).

3. DESIGN.md got the heaviest pass since it had drifted from reality,
not just tone: it still said 'no flake.nix yet' (there is one, in
production use via samfelag), claimed several things 'not yet
re-verified live' that have since been verified multiple times
(tick's no-op gate, triage, the tag-consistency/escalation decision,
pi against real heading content via tick), and didn't mention
'diwan remote' or the actual flake.nix packaging shape anywhere.
Rewrote the verified-live claims and Known Gaps list to match current
reality, added flake.nix to the doc map and architecture section.

Live content migrated to match: diwan-dev-notes' decorate-home heading
('Close diwan session' checkbox -> TODO).
2026-11-09 23:17:17 +01:00

32 lines
3.6 KiB
Markdown

# 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 piece of work — answered a chat question with real content, completed a chunk of delegated research, moved something, left Marc a note he hasn't seen yet, did something worth telling him 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 `TODO` subheading whose title is itself a 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. The bar is broad — this report is the one place Marc checks for what's new, so err on the side of reporting rather than staying quiet — but it's still per *result*, not per step: don't write five entries narrating your own process, write one once there's something to show. 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 mark the `Close diwan session` item `DONE` yourself; that's Marc's call, acted on by the next `diwan tick`, not yours.