ov-kanban

# OV Kanban A board is a directory in OpenViking that holds many tasks. A task is one markdown file. The file is both the ticket and the handoff: whoever reads it can continue the work without the previous conversation. OpenViking stores it, indexes it (`find`/`grep`), and shares it across every agent and user of the account. There is no other state. ```text <root>/<board>/<id>.md the task: header + current state, rewritten every turn <root>/<board>/archive/<id>.md its folded detail: append-only, never rewritten ``` - `<root>` is `viking://agent/kanban`. Probe it once per session with `ov stat viking://agent/kanban` (or `ov mkdir` when it does not exist yet); if the server answers `PERMISSION_DENIED` (older servers block writes under `viking://agent` except skills), use `viking://resources/kanban` instead. `$OV_KANBAN_ROOT`, when set, overrides the probe. The protocol is identical, only the root changes. - `<board>` is the isolation unit (a project, repo, or team). It is a plain directory: `ov acl` on it decides who may read or take tasks. Create one with `ov mkdir <root>/<board>` and `ov mkdir <root>/<board>/archive` (`write --mode create` needs the parent directory to exist). - `<id>` is `YYYY-MM-DD-short-slug`, unique inside the board. Use the `ov` CLI (works from any agent that has a shell). If the OpenViking MCP tools `list`, `read`, `write`, `grep` are registered, they are equivalent; never fall back to raw HTTP. Prefer the CLI for writes: a `write` that runs into the MCP client timeout has usually still landed, so `read` the file back before writing again. ## Read in layers Detail is folded, not compressed: a lower layer holds the full text the upper layer points to. Read top-down and stop at the first layer that answers the question. | layer | what it holds | how to read | |---|---|---| | boards | one abstract per board | `ov ls <root>` | | board view | `title`, `status`, `owner`, `updated` of every task | the `ov grep` below | | task | current state, enough to continue the work | `ov read <root>/<board>/<id>.md` | | archive | everything folded out of the task, verbatim | `ov grep '<keyword>' -u <root>/<board>/archive/<id>.md`, then `ov read` | ```bash ov grep '^(title|status|owner|updated):' -u <root>/<board> -x <root>/<board>/archive -o json ``` Open the archive only when a `Decisions` or `Progress` line needs its history or evidence. `ov find "<topic>" -u <root>` locates related tasks across boards. ## Task file Copy [references/task-template.md](references/task-template.md). Header: | field | values | |---|---| | `id` | `YYYY-MM-DD-short-slug`, equals the file name | | `title` | one line | | `status` | `open` · `in_progress` · `needs_user` · `blocked` · `done` · `cancelled` | | `owner` | agent id currently holding the task, empty when handed off | | `board` | the board directory name | | `updated` | output of `date +%Y-%m-%dT%H:%M:%S%z`, set on every write | Body sections, in this order: `Goal` (done criteria checklist), `Context` (cwd/repo/branch, key files or URIs, constraints), `Decisions` (dated, with why; user answers land here), `Progress` (verified only, one line per item with its evidence), `Next` (ordered checklist; first unchecked box is the next action), `Questions` (concrete questions for the user; non-empty means `status: needs_user`), `Log` (one dated line per turn, the last 10). The file is the truth. If it disagrees with the live repo, trust the repo, fix the file, and say so in `Log`. Write the body in the task's main language: the language the user gave the task in, or the one an existing task already uses. Header keys and status values stay English. ## Fold The task file stays short enough to read in one call. Text leaves it by moving to the archive, never by deletion or by a shorter rewrite: - `Log` lines beyond the last 10; - `Next` steps and `Decisions` that a later turn replaced; - evidence longer than one line (command output, diff summary, review notes): the `Progress` line keeps the result, the archive keeps the rest. Append one entry per turn: a `### <updated> <agent id>` heading, the status change as `from -> to` when there is one, then the moved text verbatim. ```bash ov write <root>/<board>/archive/<id>.md --append --from-file ./entry.md --wait ``` Create the archive with `--mode create` the first time. A turn that moves nothing out and keeps the status writes no entry. ## One turn Every turn is bounded: pick, claim, one slice, verify, write back, stop. 1. **Pick.** Read the board view (the `ov grep` above). Take the task the user named, else an `open` one, else an `in_progress` one whose `updated` is older than 2 hours (stale claim). Skip `in_progress` tasks another agent updated recently. 2. **Claim.** `ov read` the file. Set `status: in_progress`, `owner: <your agent id>`, `updated: now`, add a `Log` line, write back (step 5). Agent id is `$OV_KANBAN_AGENT` if set, else `<tool>@<host>` (e.g. `codex@mbp`). 3. **Slice.** Do the first unchecked item in `Next`, or more while it stays one coherent, verifiable piece of work. Read `Context` and `Decisions` first; they are the contract from earlier turns and the user. 4. **Verify.** Run the check that proves the slice (test, build, command output, diff). Only verified work goes into `Progress`, with its evidence. 5. **Write back.** Fold first (see above), then rewrite the whole file with the updated header and body: ```bash ov write <root>/<board>/<id>.md --from-file ./task.md --wait ``` On `CONFLICT` (path busy) wait a few seconds and retry once; on `ALREADY_EXISTS` when creating (`--mode create`) pick another id. Then choose the exit state: - more to do and you continue next turn → keep `in_progress`; - handing off (context nearly full, wrong tool, or the user asked) → clear `owner`, set `status: open`, make sure `Next` is precise enough for a cold reader; - a decision only the user can make → write the question in `Questions`, set `status: needs_user`, clear `owner`, then ask the user in the current session if there is one and stop; - waiting on something external (a PR review, another task) → `blocked`, name what unblocks it in `Next`; - all `Goal` boxes ticked with evidence → `done`; - the user dropped the task → `cancelled`, clear `owner`, record who decided and why in `Decisions`. Creating a task is the same write with `--mode create` and `status: open`; fill `Goal` and `Context` from the user's request and put the first concrete step in `Next`. Answering a `needs_user` task: record the answer in `Decisions`, clear `Questions`, set `status: open`, write back. The next turn picks it up. ## Long-running and multi-agent - **Unattended loop.** [references/loop.sh](references/loop.sh) runs one agent turn after another (`codex exec` by default, any CLI via `OV_KANBAN_CMD`) until no runnable task is left or the tick budget is spent, and notifies through herdr when it stops. `needs_user` tasks are not runnable, so the loop drains around them and stops when only those remain. ```bash bash references/loop.sh <board> 5 /path/to/repo ``` - **Cross-agent handoff.** Any agent that reads the file continues it; Claude, Codex, or a human via `ov tui`. Nothing is tool-specific except the agent id in `owner`. - **Handoff to a person.** A step only a person can do (approve a release, run a privileged command) is a `needs_user` gate: name the person and the exact action in `Questions`, clear `owner`, stop. When they report back, record the outcome in `Decisions` and set `status: open`. - **Several tasks at once.** Give each subagent its own agent id and one task; they never share a file. Serialize tasks that touch the same files by listing the dependency in `Next` and setting the later one `blocked`. ## Rules - Never claim a task another agent updated within the last 2 hours. - Never write secrets, tokens, or raw logs into a task or its archive; write conclusions and the evidence that backs them. - Never mark `Progress` without evidence, never mark `done` with an unchecked `Goal` box. - Never drop text from a task file; fold it into the archive. - Do not run a second task in the same turn; write back, then pick again.