Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(agent-plugins): rename ov-tasks to ov-kanban, fold task detail into archive (#5451)
Zayn Jarvis5b2345944e77
diff --git a/agent-plugins/README.md b/agent-plugins/README.mdindex 06792eb1c..09286b923 100644--- a/agent-plugins/README.md+++ b/agent-plugins/README.md@@ -15,7 +15,7 @@ skills/openviking-memory/SKILL.md # teaches the model the recall + persist loskills/ov-memory-troubleshoot/ # read-only extraction troubleshootingskills/ov-experience-memory/ # retrieve and apply prior task Experienceskills/openviking-skills/ # find, use, create, and share OpenViking skills-skills/ov-tasks/ # task board: pick, execute, hand off tasks stored as OV markdown files+skills/ov-kanban/ # kanban board: pick, execute, hand off tasks stored as OV markdown filesplugin.test.mjs # node --test conformance checks```@@ -25,7 +25,7 @@ Use `ov-memory-troubleshoot` to trace backward from a memory file to its archive`openviking-skills` covers the skills stored in OpenViking itself: how to find one with `find(context_type="skill")`, read and follow its `SKILL.md`, create or replace one with the `add_skill` MCP tool, install one from Git or a local folder, share one with the account, and move local skill folders into OpenViking when you ask. This package has no session-start hook, so there is no `<available-skills>` catalog here and the skill has the model search for a skill instead.-Use `ov-tasks` to run long or multi-agent work through a task board in OpenViking: each task is one markdown file (`viking://agent/tasks/<scope>/<id>.md`, falling back to `viking://resources/tasks` on servers that reject writes under `viking://agent`) whose header and body are the handoff, so any agent with the `ov` CLI can claim, continue, and write it back. `references/loop.sh` drives unattended ticks; see [docs/design/ov-tasks.md](../docs/design/ov-tasks.md).+Use `ov-kanban` to run long or multi-agent work through a kanban board in OpenViking. A board holds many tasks; each task is one markdown file (`viking://agent/kanban/<board>/<id>.md`, falling back to `viking://resources/kanban` on servers that reject writes under `viking://agent`) whose header and body are the handoff, so any agent with the `ov` CLI can claim, continue, and write it back. Process detail is folded into `archive/<id>.md` instead of being summarized away, and agents read in layers: board view, task, archive. `references/loop.sh` drives unattended ticks; see the skill's [README](skills/ov-kanban/README.md) for the idea and roadmap, and [docs/design/ov-kanban.md](../docs/design/ov-kanban.md) for design notes.Zero npm dependencies; the proxy and tests run on the Node.js standard library (Node 18+ for global `fetch`).@@ -34,7 +34,7 @@ Zero npm dependencies; the proxy and tests run on the Node.js standard library (1. Have an OpenViking server reachable (see the [quickstart](../docs/en/getting-started/02-quickstart.md)); default local endpoint is `http://127.0.0.1:1933`.2. Point your Agent-Plugins-conforming client at this directory (each client has its own install command or plugin directory; consult its docs). The client will:- register the `openviking` MCP server from `mcp.json` — it runs `node <plugin>/servers/mcp-proxy.mjs` over stdio;- - discover the `openviking-memory`, `ov-memory-troubleshoot`, `ov-experience-memory`, `openviking-skills`, and `ov-tasks` skills from `skills/`.+ - discover the `openviking-memory`, `ov-memory-troubleshoot`, `ov-experience-memory`, `openviking-skills`, and `ov-kanban` skills from `skills/`.3. Configure credentials (next section) and start a session. The model gains `find` / `search` / `read` / `remember` / `write` / `add_skill` and the other OpenViking MCP tools. Use `search` with `mode="context"` for server-assembled context.## Why a stdio proxy instead of a `streamable-http` entrydiff --git a/agent-plugins/skills/ov-kanban/README.md b/agent-plugins/skills/ov-kanban/README.mdnew file mode 100644index 000000000..42ffef9f7--- /dev/null+++ b/agent-plugins/skills/ov-kanban/README.md@@ -0,0 +1,51 @@+# ov-kanban++A kanban board for agents, stored in OpenViking. `SKILL.md` is the protocol+agents follow; this file is for people: the idea and the roadmap.++## Idea++An agent works on a long task across many sessions, tools, and people. Each+session starts cold, so the task state has to live outside the conversation.+The usual answer is to compress: summarize the history, keep the summary,+drop the rest. The summary loses the detail the next turn turns out to need.++ov-kanban folds instead. The board keeps every task's process, arranged in+layers, and the agent reads down only as far as the question requires:++| layer | content | cost |+| --- | --- | --- |+| boards | one abstract per board | one `ov ls` |+| board view | title, status, owner, updated of every task | one `ov grep` |+| task | goal, context, decisions, verified progress, next steps | one `ov read` |+| archive | replaced plans, old log lines, full evidence, verbatim | `ov grep` / `ov read` on demand |++Text leaves a task file by moving to its archive, never by deletion. The+task file stays short, the history stays complete, and an agent that needs a+detail from three weeks ago greps for it.++A board holds many tasks. Agents keep working by taking the next runnable+task off the board: pick, claim, one slice, verify, fold, write back.++## Layout++```text+viking://agent/kanban/<board>/<id>.md task+viking://agent/kanban/<board>/archive/<id>.md folded detail+```++Servers that reject writes under `viking://agent` use+`viking://resources/kanban`. Design notes, the mapping to PowerContext and+LoopX, and the rehearsal record are in+[docs/design/ov-kanban.md](../../../docs/design/ov-kanban.md).++## Roadmap++| item | today | target |+| --- | --- | --- |+| Task DAG | A dependency is prose in `Next` plus `status: blocked`. | Header field `blocked_by: [<board>/<id>, ...]`. A task is runnable when every blocker is `done`. The board view shows the runnable frontier, and `loop.sh` picks from it. Edges may cross boards. |+| Scoped kanban | The agent is told the board name. | A board declares its scope (repo, directories, branches) in `<board>/BOARD.md`. Recall matches the session's cwd and branch against board scopes, so a session sees the boards that concern its work and no others. |+| Recall on session start | The agent reads the board when the skill triggers. | Hook plugins inject the board view of matching boards at session start. Depends on scoped kanban. |+| Claim-aware loop | `loop.sh` counts every `open` or `in_progress` task as runnable, so a tick can find nothing to claim. | Count `open` tasks, stale claims, and the caller's own claims. |+| Atomic claim | `owner` + `updated` with a 2-hour convention; two agents can claim the same task at once. | Compare-and-set on write, once OpenViking `write` supports it. |+| `ov compile` | Not supported: compile rejects kanban targets and file sources. | `ov compile --from <board> --to <board> --skill ov-kanban` runs one turn on the server. Blockers are listed in the design doc. |diff --git a/agent-plugins/skills/ov-kanban/SKILL.md b/agent-plugins/skills/ov-kanban/SKILL.mdnew file mode 100644index 000000000..53d673573--- /dev/null+++ b/agent-plugins/skills/ov-kanban/SKILL.md@@ -0,0 +1,180 @@+---+name: ov-kanban+description: Work through tasks on a kanban board stored in OpenViking (viking://agent/kanban/<board>/, one markdown file per task). Use when the user says "ov kanban", "kanban", "看板", asks to put a task on the board, hand off the current work, continue a task another agent started, or run an unattended task loop. A board holds many tasks; each task file is the handoff itself - a frontmatter header (id, status, owner, board) plus Goal, Context, Decisions, Progress, Next, Questions, Log - and its process detail is folded into an archive file instead of being summarized away, so any agent with the `ov` CLI can resume it and drill down when needed.+---++# 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.diff --git a/agent-plugins/skills/ov-kanban/references/loop.sh b/agent-plugins/skills/ov-kanban/references/loop.shnew file mode 100644index 000000000..7b99a2fa4--- /dev/null+++ b/agent-plugins/skills/ov-kanban/references/loop.sh@@ -0,0 +1,56 @@+#!/usr/bin/env bash+# loop.sh — run one CLI agent turn after another against an ov-kanban board+# until no runnable task remains or the tick budget is spent.+#+# bash loop.sh <board> [max_ticks=5] [cwd=$PWD]+#+# env:+# OV_KANBAN_ROOT kanban root (default: viking://agent/kanban, falls back to+# viking://resources/kanban when the server rejects agent/kanban)+# OV_KANBAN_AGENT agent id written as owner (default codex@<host>)+# OV_KANBAN_CMD agent command template with {PROMPT} placeholder+# (default: codex exec, non-interactive, prompt from file)+#+# Each tick = one bounded turn of the ov-kanban skill: pick, claim, one slice,+# verify, write back. The task file in OV is the only state between ticks.+# ponytail: max_ticks is the whole quota model; add per-task budgets if a task+# ever spins.+set -uo pipefail++board="${1:?board}"; max_ticks="${2:-5}"; cwd="${3:-$PWD}"+# root: viking://agent/kanban when the server accepts it, else viking://resources/kanban+ov_ok() { command ov "$@" -o json 2>&1 | grep -q '^{"ok":true'; }+if [ -z "${OV_KANBAN_ROOT:-}" ]; then+ if ov_ok stat viking://agent/kanban || ov_ok mkdir viking://agent/kanban; then OV_KANBAN_ROOT=viking://agent/kanban+ else OV_KANBAN_ROOT=viking://resources/kanban; fi+fi+: "${OV_KANBAN_AGENT:=codex@$(hostname -s)}"+[ -n "${OV_KANBAN_CMD:-}" ] || OV_KANBAN_CMD="codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check -C \"${cwd}\" - < {PROMPT}"+skill_md="$(cd "$(dirname "$0")/.." && pwd)/SKILL.md"+board_uri="${OV_KANBAN_ROOT}/${board}"++# ponytail: counts every open|in_progress task, including one another agent+# claimed minutes ago, so a tick can find nothing to claim. Filter on+# owner/updated here if idle ticks start to cost.+runnable() {+ command ov grep '^status: (open|in_progress)' -u "$board_uri" -x "$board_uri/archive" -o json 2>/dev/null \+ | python3 -c 'import sys,json; d=json.loads(next(l for l in sys.stdin if l.startswith("{"))); print(len({m["uri"] for m in d.get("result",{}).get("matches",[])}))' 2>/dev/null || echo 0+}+notify() { command -v herdr >/dev/null && herdr notification show "$1" --sound done >/dev/null 2>&1; echo "$1"; }++for tick in $(seq 1 "$max_ticks"); do+ n=$(runnable)+ if [ "$n" = 0 ]; then notify "ov-kanban ${board}: no runnable task (needs_user/blocked/done only)"; exit 0; fi+ prompt="$(mktemp "${TMPDIR:-/tmp}/ov-kanban-prompt.XXXXXX")"+ cat > "$prompt" <<PROMPT+Read ${skill_md} and follow it exactly.+Kanban root: ${OV_KANBAN_ROOT} board: ${board} your agent id: ${OV_KANBAN_AGENT}+Do exactly ONE turn: pick one runnable task on this board, claim it, do one bounded slice, verify it, fold and write the task file back, then stop.+If the task needs a user answer, set status: needs_user, put the concrete question in ## Questions, write back, and stop.+Do not start a second task in this turn.+PROMPT+ echo "== tick ${tick}/${max_ticks} (${n} runnable) =="+ eval "${OV_KANBAN_CMD//\{PROMPT\}/$prompt}"+ rm -f "$prompt"+done+notify "ov-kanban ${board}: tick budget ${max_ticks} spent, $(runnable) runnable left"diff --git a/agent-plugins/skills/ov-tasks/references/task-template.md b/agent-plugins/skills/ov-kanban/references/task-template.mdsimilarity index 74%rename from agent-plugins/skills/ov-tasks/references/task-template.mdrename to agent-plugins/skills/ov-kanban/references/task-template.mdindex 170dfdb32..449689c6b 100644--- a/agent-plugins/skills/ov-tasks/references/task-template.md+++ b/agent-plugins/skills/ov-kanban/references/task-template.md@@ -3,7 +3,7 @@ id: 2026-09-18-short-slugtitle: One-line task titlestatus: openowner:-scope: demo+board: demoupdated: 2026-09-18T12:00:00+0800---@@ -19,7 +19,7 @@ cwd / repo / branch, key files or viking:// URIs, constraints, docs that have au- 2026-09-18: decision — why. User answers to Questions are recorded here too.## Progress-Verified progress only, each line with its evidence (command + result, commit, PR, file path).+Verified progress only, one line each with its evidence (command + result, commit, PR, file path). Longer evidence is folded into the archive.## Next- [ ] ordered steps; the first unchecked box is what the next agent does@@ -28,4 +28,5 @@ Verified progress only, each line with its evidence (command + result, commit, PConcrete questions the user must answer. Non-empty means `status: needs_user`.## Log+Last 10 turns. Older lines and full evidence: `archive/2026-09-18-short-slug.md`.- 2026-09-18T12:00 agent-id: createddiff --git a/agent-plugins/skills/ov-tasks/SKILL.md b/agent-plugins/skills/ov-tasks/SKILL.mddeleted file mode 100644index 3e8e4ce04..000000000--- a/agent-plugins/skills/ov-tasks/SKILL.md+++ /dev/null@@ -1,145 +0,0 @@-----name: ov-tasks-description: Pick up, execute, and hand off long-running tasks stored as structured markdown files in OpenViking (task board under viking://agent/tasks/<scope>/). Use when the user says "ov tasks", asks to create a task on the board, hand off the current work, continue a task another agent started, or run an unattended task loop. Each task file is the handoff itself - a frontmatter header (id, status, owner, scope) plus Goal, Context, Decisions, Progress, Next, Questions, Log - so any agent with the `ov` CLI can resume it.------# OV Tasks--A task is one markdown file in OpenViking. 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>/<scope>/<id>.md the task (header + handoff body), rewritten every turn-<root>/<scope>/archive/<id>.md optional append-only history of status transitions-```--- `<root>` is `viking://agent/tasks`. Probe it once per session with- `ov stat viking://agent/tasks` (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/tasks` instead.- `$OV_TASKS_ROOT`, when set, overrides the probe. The protocol is identical,- only the root changes.-- `<scope>` 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>/<scope>` and `ov mkdir <root>/<scope>/archive`- (`write --mode create` needs the parent directory to exist).-- `<id>` is `YYYY-MM-DD-short-slug`, unique inside the scope.--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.--## 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 |-| `scope` | the scope directory name |-| `updated` | ISO time with offset, 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, with 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, keep 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.--## One turn--Every turn is bounded: pick, claim, one slice, verify, write back, stop.--1. **Pick.** List runnable tasks in the scope:- ```bash- ov grep '^status: (open|in_progress)' -u <root>/<scope> -x <root>/<scope>/archive -o json- ```- 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_TASKS_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.** Rewrite the whole file with the updated header and body:- ```bash- ov write <root>/<scope>/<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`.-6. **Archive (optional).** On every status change append one entry to- `<root>/<scope>/archive/<id>.md`: the timestamp, `from -> to`, owner, and- the current `Progress` + `Next` sections. Create it with `--mode create`- the first time; the task file itself never moves.- ```bash- ov write <root>/<scope>/archive/<id>.md --append --from-file ./entry.md --wait- ```--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_TASKS_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- zsh references/loop.sh <scope> 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`.-- **Retrieval.** `ov find "<topic>" -u <root>` locates related tasks- across scopes; `ov ls <root>/<scope>` shows abstracts for a quick scan.--## Rules--- Never claim a task another agent updated within the last 2 hours.-- Never write secrets, tokens, or raw logs into a task; write conclusions.-- Never mark `Progress` without evidence, never mark `done` with an- unchecked `Goal` box.-- Do not run a second task in the same turn; write back, then pick again.diff --git a/agent-plugins/skills/ov-tasks/references/loop.sh b/agent-plugins/skills/ov-tasks/references/loop.shdeleted file mode 100644index 84cd8088f..000000000--- a/agent-plugins/skills/ov-tasks/references/loop.sh+++ /dev/null@@ -1,52 +0,0 @@-#!/bin/zsh-# loop.sh — run one CLI agent turn after another against an ov-tasks scope-# until no runnable task remains or the tick budget is spent.-#-# zsh loop.sh <scope> [max_ticks=5] [cwd=$PWD]-#-# env:-# OV_TASKS_ROOT task board root (default: viking://agent/tasks, falls back to-# viking://resources/tasks when the server rejects agent/tasks)-# OV_TASKS_AGENT agent id written as owner (default codex@<host>)-# OV_TASKS_CMD agent command template with {PROMPT} placeholder-# (default: codex exec, non-interactive, prompt from file)-#-# Each tick = one bounded turn of the ov-tasks skill: pick, claim, one slice,-# verify, write back. The task file in OV is the only state between ticks.-# ponytail: max_ticks is the whole quota model; add per-task budgets if a task-# ever spins.-set -uo pipefail--scope="${1:?scope}"; max_ticks="${2:-5}"; cwd="${3:-$PWD}"-# root: viking://agent/tasks when the server accepts it, else viking://resources/tasks-ov_ok() { command ov "$@" -o json 2>&1 | grep -q '^{"ok":true'; }-if [ -z "${OV_TASKS_ROOT:-}" ]; then- if ov_ok stat viking://agent/tasks || ov_ok mkdir viking://agent/tasks; then OV_TASKS_ROOT=viking://agent/tasks- else OV_TASKS_ROOT=viking://resources/tasks; fi-fi-: "${OV_TASKS_AGENT:=codex@$(hostname -s)}"-: "${OV_TASKS_CMD:=codex exec --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check -C ${cwd} - < {PROMPT\}}"-skill_md="${0:A:h:h}/SKILL.md"-scope_uri="${OV_TASKS_ROOT}/${scope}"--runnable() {- command ov grep '^status: (open|in_progress)' -u "$scope_uri" -x "$scope_uri/archive" -o json 2>/dev/null \- | python3 -c 'import sys,json; d=json.loads(next(l for l in sys.stdin if l.startswith("{"))); print(len({m["uri"] for m in d.get("result",{}).get("matches",[])}))' 2>/dev/null || echo 0-}-notify() { command -v herdr >/dev/null && herdr notification show "$1" --sound done >/dev/null 2>&1; echo "$1"; }--for tick in $(seq 1 "$max_ticks"); do- n=$(runnable)- if [ "$n" = 0 ]; then notify "ov-tasks ${scope}: no runnable task (needs_user/blocked/done only)"; exit 0; fi- prompt="$(mktemp -t ov-tasks-prompt.XXXXXX.md)"- cat > "$prompt" <<PROMPT-Read ${skill_md} and follow it exactly.-Task board root: ${OV_TASKS_ROOT} scope: ${scope} your agent id: ${OV_TASKS_AGENT}-Do exactly ONE turn: pick one runnable task in this scope, claim it, do one bounded slice, verify it, write the task file back, then stop.-If the task needs a user answer, set status: needs_user, put the concrete question in ## Questions, write back, and stop.-Do not start a second task in this turn.-PROMPT- echo "== tick ${tick}/${max_ticks} (${n} runnable) =="- eval "${OV_TASKS_CMD//\{PROMPT\}/$prompt}"-done-notify "ov-tasks ${scope}: tick budget ${max_ticks} spent, $(runnable) runnable left"diff --git a/docs/design/ov-kanban.md b/docs/design/ov-kanban.mdnew file mode 100644index 000000000..f31c765c1--- /dev/null+++ b/docs/design/ov-kanban.md@@ -0,0 +1,100 @@+# ov-kanban:把结构化 handoff 做成 OpenViking 上的看板++| 项目 | 信息 |+| --- | --- |+| 状态 | 可用(skill 已落地,herdr 演练通过) |+| Skill | `agent-plugins/skills/ov-kanban/`(原名 `ov-tasks`,PR #5157) |+| 存储 | `viking://agent/kanban/<board>/<id>.md`;server 拒绝时兜底 `viking://resources/kanban`(见下) |+| 更新日期 | 2026-09-29 |++## 一句话++一个看板 = OV 里的一个目录,存放多个任务。一个任务 = 一个 markdown 文件:frontmatter 头(id/status/owner/board/updated)+ 固定七段正文(Goal/Context/Decisions/Progress/Next/Questions/Log)。文件本身就是 handoff,任何有 `ov` CLI 的 agent 读到就能继续,每轮结束整文件写回。过程详情折叠进 `archive/<id>.md`,不删除。没有其他状态。++## 改名原因(2026-09-29)++| 原因 | 说明 |+| --- | --- |+| 与 CLI 重名 | `ov task list` 指 server 的异步处理任务,`ov-tasks` 与之混淆 |+| 容器语义 | 看板存放多个任务;`tasks` 这个名字指不出容器 |+| `scope` 让位 | 原 `<scope>` 目录改称 `<board>`;`scope` 留给 roadmap 的 scoped kanban(看板声明自己关联的目录、分支) |++## 折叠,不压缩++长任务跨多个会话,状态必须在会话之外。压缩(摘要后丢弃原文)会丢掉下一轮需要的细节。ov-kanban 把过程折叠成层,agent 自上而下读,读到能回答问题的那一层为止。++| 层 | 内容 | 读取 |+| --- | --- | --- |+| 看板列表 | 每个看板一条摘要 | `ov ls <root>` |+| 看板视图 | 每个任务的 title/status/owner/updated | `ov grep '^(title\|status\|owner\|updated):'`,一次调用 |+| 任务文件 | 当前状态,足够继续工作 | `ov read` |+| archive | 从任务文件移出的原文:被替换的 Next/Decisions、10 行以外的 Log、超过一行的证据 | 按需 `ov grep` / `ov read` |++不变量:文本只能通过移入 archive 离开任务文件。PR #5157 的版本里 `Log` 只保留最近 10 行(其余丢弃)、archive 为可选,本次改为上述规则。++## 与 PowerContext / LoopX 的对应++| 概念 | PowerContext | LoopX | ov-kanban |+| --- | --- | --- | --- |+| 隔离边界 | Scope(server 生成的 opaque id) | Goal + project registry | `<root>/<board>/` 目录,`ov acl` 管权限 |+| 目标与完成边界 | Work Contract | Objective + Operating Contract | `## Goal` 验收清单 + `## Context` |+| 交接内容 | Prepared/Committed Handoff | ACTIVE_GOAL_STATE.md | 任务文件全文 |+| 待办 | — | Agent Todo / User Todo | `## Next` 清单 / `## Questions` + `status: needs_user` |+| 用户门 | Acknowledgement needs clarification | user gate | `status: needs_user`,agent 在会话内向用户提问并停下 |+| 证据 | Source / Task Outcome | evidence + Progress Ledger | `## Progress`(只写已验证条目,带证据)+ `## Log` |+| 所有权 | receiver acknowledgement | claim / lease | `owner` + `updated`;超过 2h 未更新视为可重新认领 |+| 历史 | 不可变 Revision + lineage | run history | `archive/<id>.md`,追加式;status 变化和折叠出的原文都写入 |+| 长期运行 | — | quota + scheduler + kernel | `references/loop.sh`:一轮一次 agent 调用,直到无可跑任务或轮数用尽 |+| 跨 agent | 同 Scope 内继续 Handoff | peer agents + writeback | 同一文件;agent id 写在 `owner` |+| 检索 | Handoff Report | `loopx status` | 看板视图(`ov grep`)、`ov find`、`ov ls` |++## 丢弃的概念与原因++| 丢弃 | 原因 |+| --- | --- |+| LoopX Kernel / Capability / Provider / Extension 分层 | OV 只负责存储与检索;执行方是任意 CLI agent。分层没有承载者,30 行 loop.sh 覆盖"一轮一 tick"。 |+| LoopX quota / 调度 / 自修复 | 用 `max_ticks` 一个数字替代。任务不会自旋,因为每轮必须写回且 needs_user 不可跑。 |+| LoopX typed claim / lease / 原子 writeback | OV write 没有 CAS。用 `owner`+`updated` 的 2h 约定替代,并在 skill 中写明。并发同一任务是已知上限。 |+| PowerContext 不可变 Revision / lineage / Acknowledgement / Task Outcome | 四个对象折叠为一个可变文件 + 追加式 archive。Acknowledgement = claim 时写 Log;Outcome = 最终 status + Progress。 |+| PowerContext Candidate 审核、Experience/Skill 家族 | 与 handoff 无关;经验沉淀走 OV 已有的 `remember`。 |+| PowerContext opaque scope id | OV URI 本身就是 scope 且带 ACL,不需要第二套 id。 |+| Dashboard / Lark 看板投影 | `ov ls`、`ov tui`、`ov find` 已够;需要时再做。 |+| retrieval tags 镜像 status/owner | 云端 0.4.17.3 的 write 不接受 `--tags`,需要第二次 `set-tags` 调用;frontmatter + `ov grep` 已能过滤,避免双写漂移。 |++## 存储位置:viking://agent/kanban 优先,探测失败兜底 viking://resources/kanban++| 事实 | 证据 |+| --- | --- |+| 云端 server 拒绝 `viking://agent/<非 skills>` 的 mkdir/write(v0.4.17.3 用 `agent/tasks` 验证;2026-09-29 `loop.sh` 探测 `agent/kanban` 同样退回兜底) | `PERMISSION_DENIED: viking://agent/{agent_id} is deprecated. Use viking://user/.../peers/{agent_id}` |+| main 分支 namespace 只把 `agent/skills` 视为内容目录 | `openviking/core/namespace.py:16` `_CONTENT_TYPES_BY_SCOPE["agent"] = {"skills": "skill"}`;`viking://agent/<其他目录>/x.md` 得到 `context_type=resource`,main 上无显式写保护 |+| `viking://resources/kanban` 在云端可用:create / read / append / grep 均通过 | 本文演练;原 `viking://resources/tasks` 已于 2026-09-29 用 `ov mv` 迁入 |++开源 main 已允许在 `viking://agent` 下新建目录。skill 与 loop.sh 每次先 `ov stat`/`ov mkdir viking://agent/kanban` 探测,失败才退回 `viking://resources/kanban`;`OV_KANBAN_ROOT` 可强制指定。协议与 root 无关。++## `ov compile` 接入(下一步)++目标:`ov compile --from <root>/<board> --to <root>/<board> --skill viking://agent/skills/ov-kanban`,由 VikingBot 按 skill 执行一轮并把任务文件写回。++| 阻塞点 | 位置 |+| --- | --- |+| `--to` 只允许 resource/memory/skills 目录 | `openviking/service/compile_service.py:464` `_validate_target`(`viking://agent/kanban/<board>` 需放行) |+| `--from` 必须是目录 | `compile_service.py:446`,单任务文件需放行文件源,或约定 from = board 目录 + `--instruction "task <id>"` |+| Compile agent 的产物是 wiki bundle(`submit_wiki_bundle`) | 需要一个"原地改写源文件"的输出工具;改动在 VikingBot 侧 |++建议顺序:先把 `ov-kanban` 用 `ov add-skill agent-plugins/skills/ov-kanban -p viking://agent/skills` 装到 OV,再改 compile 的两处校验,最后补写回工具。++## Roadmap++任务 DAG(`blocked_by`)、scoped kanban、会话启动召回、claim-aware loop、原子 claim、`ov compile`,见 [skill README](https://github.com/volcengine/OpenViking/blob/main/agent-plugins/skills/ov-kanban/README.md#roadmap)。++## 演练记录(2026-09-18,herdr,board `demo`)++演练时 skill 名为 `ov-tasks`,存储在 `viking://resources/tasks/demo`。++| 轮 | 执行者 | 动作 | 结果 |+| --- | --- | --- | --- |+| A | codex(`codex exec`) | 认领 `wc-top`,只做 Next 第一项,验证后 handoff(status open、owner 清空) | 文件写回正确;archive 记录 open→in_progress→open;脚本可运行 |+| B | claude(`claude -p`) | 读 A 的 handoff 继续,补测试和 README | status done,Goal 三项全勾且带证据;本地复跑 `pytest` 4 passed |+| C | `loop.sh demo 4` 驱动 codex | tick1 认领 `makefile`:写好 Makefile,但本机 `make` 被 Xcode license 挡住 → `needs_user` 并写明问题;tick2 认领 `report-format`:输出格式未定 → `needs_user`;tick3 无可跑任务,循环停止 | 两次 user gate 都是真实阻塞,没有假 pass;循环按预期收敛 |++演练中修的两个问题:`write --mode create` 需要 `archive/` 目录先存在(skill 已写明);`ov` 输出 JSON 前有一行 `cmd:`,loop.sh 改为只解析 JSON 行。另外 codex 侧的 OV MCP `write` 会在 15s 超时后仍写入成功,skill 已注明优先用 CLI 并回读确认。diff --git a/docs/design/ov-tasks.md b/docs/design/ov-tasks.mddeleted file mode 100644index 46ab0027d..000000000--- a/docs/design/ov-tasks.md+++ /dev/null@@ -1,73 +0,0 @@-# ov-tasks:把结构化 handoff 做成 OpenViking 上的任务板--| 项目 | 信息 |-| --- | --- |-| 状态 | 可用(skill 已落地,herdr 演练通过) |-| Skill | `agent-plugins/skills/ov-tasks/` |-| 存储 | `viking://agent/tasks/<scope>/<id>.md`;server 拒绝时兜底 `viking://resources/tasks`(见下) |-| 更新日期 | 2026-09-18 |--## 一句话--一个任务 = OV 里的一个 markdown 文件:frontmatter 头(id/status/owner/scope/updated)+ 固定七段正文(Goal/Context/Decisions/Progress/Next/Questions/Log)。文件本身就是 handoff,任何有 `ov` CLI 的 agent 读到就能继续,每轮结束整文件写回。没有其他状态。--## 与 PowerContext / LoopX 的对应--| 概念 | PowerContext | LoopX | ov-tasks |-| --- | --- | --- | --- |-| 隔离边界 | Scope(server 生成的 opaque id) | Goal + project registry | `<root>/<scope>/` 目录,`ov acl` 管权限 |-| 目标与完成边界 | Work Contract | Objective + Operating Contract | `## Goal` 验收清单 + `## Context` |-| 交接内容 | Prepared/Committed Handoff | ACTIVE_GOAL_STATE.md | 任务文件全文 |-| 待办 | — | Agent Todo / User Todo | `## Next` 清单 / `## Questions` + `status: needs_user` |-| 用户门 | Acknowledgement needs clarification | user gate | `status: needs_user`,agent 在会话内向用户提问并停下 |-| 证据 | Source / Task Outcome | evidence + Progress Ledger | `## Progress`(只写已验证条目,带证据)+ `## Log` |-| 所有权 | receiver acknowledgement | claim / lease | `owner` + `updated`;超过 2h 未更新视为可重新认领 |-| 历史 | 不可变 Revision + lineage | run history | 可选 `archive/<id>.md`,只在 status 变化时追加 |-| 长期运行 | — | quota + scheduler + kernel | `references/loop.sh`:一轮一次 agent 调用,直到无可跑任务或轮数用尽 |-| 跨 agent | 同 Scope 内继续 Handoff | peer agents + writeback | 同一文件;agent id 写在 `owner` |-| 检索 | Handoff Report | `loopx status` | `ov grep '^status: open'`、`ov find`、`ov ls` |--## 丢弃的概念与原因--| 丢弃 | 原因 |-| --- | --- |-| LoopX Kernel / Capability / Provider / Extension 分层 | OV 只负责存储与检索;执行方是任意 CLI agent。分层没有承载者,30 行 loop.sh 覆盖"一轮一 tick"。 |-| LoopX quota / 调度 / 自修复 | 用 `max_ticks` 一个数字替代。任务不会自旋,因为每轮必须写回且 needs_user 不可跑。 |-| LoopX typed claim / lease / 原子 writeback | OV write 没有 CAS。用 `owner`+`updated` 的 2h 约定替代,并在 skill 中写明。并发同一任务是已知上限。 |-| PowerContext 不可变 Revision / lineage / Acknowledgement / Task Outcome | 四个对象折叠为一个可变文件 + 可选追加式 archive。Acknowledgement = claim 时写 Log;Outcome = 最终 status + Progress。 |-| PowerContext Candidate 审核、Experience/Skill 家族 | 与 handoff 无关;经验沉淀走 OV 已有的 `remember`。 |-| PowerContext opaque scope id | OV URI 本身就是 scope 且带 ACL,不需要第二套 id。 |-| Dashboard / Lark 看板投影 | `ov ls`、`ov tui`、`ov find` 已够;需要时再做。 |-| retrieval tags 镜像 status/owner | 云端 0.4.17.3 的 write 不接受 `--tags`,需要第二次 `set-tags` 调用;frontmatter + `ov grep` 已能过滤,避免双写漂移。 |--## 存储位置:viking://agent/tasks 优先,探测失败兜底 viking://resources/tasks--| 事实 | 证据 |-| --- | --- |-| 云端 server (v0.4.17.3) 拒绝 `viking://agent/tasks` 的 mkdir/write | `PERMISSION_DENIED: viking://agent/{agent_id} is deprecated. Use viking://user/.../peers/{agent_id}` |-| main 分支 namespace 只把 `agent/skills` 视为内容目录 | `openviking/core/namespace.py:16` `_CONTENT_TYPES_BY_SCOPE["agent"] = {"skills": "skill"}`;`classify_uri("viking://agent/tasks/x.md")` 得到 `context_type=resource`,main 上无显式写保护 |-| `viking://resources/tasks` 在云端可用:create / read / append / grep / set-tags 均通过 | 本文演练 |--开源 main 已允许在 `viking://agent` 下新建目录。skill 与 loop.sh 每次先 `ov stat`/`ov mkdir viking://agent/tasks` 探测,`PERMISSION_DENIED` 才退回 `viking://resources/tasks`;`OV_TASKS_ROOT` 可强制指定。协议与 root 无关。--## `ov compile` 接入(下一步)--目标:`ov compile --from <root>/<scope> --to <root>/<scope> --skill viking://agent/skills/ov-tasks`,由 VikingBot 按 skill 执行一轮并把任务文件写回。--| 阻塞点 | 位置 |-| --- | --- |-| `--to` 只允许 resource/memory/skills 目录 | `openviking/service/compile_service.py:464` `_validate_target`(`viking://agent/tasks/<scope>` 需放行) |-| `--from` 必须是目录 | `compile_service.py:446`,单任务文件需放行文件源,或约定 from = scope 目录 + `--instruction "task <id>"` |-| Compile agent 的产物是 wiki bundle(`submit_wiki_bundle`) | 需要一个"原地改写源文件"的输出工具;改动在 VikingBot 侧 |--建议顺序:先把 `ov-tasks` 用 `ov add-skill agent-plugins/skills/ov-tasks -p viking://agent/skills` 装到 OV,再改 compile 的两处校验,最后补写回工具。--## 演练记录(2026-09-18,herdr,scope `demo`)--| 轮 | 执行者 | 动作 | 结果 |-| --- | --- | --- | --- |-| A | codex(`codex exec`) | 认领 `wc-top`,只做 Next 第一项,验证后 handoff(status open、owner 清空) | 文件写回正确;archive 记录 open→in_progress→open;脚本可运行 |-| B | claude(`claude -p`) | 读 A 的 handoff 继续,补测试和 README | status done,Goal 三项全勾且带证据;本地复跑 `pytest` 4 passed |-| C | `loop.sh demo 4` 驱动 codex | tick1 认领 `makefile`:写好 Makefile,但本机 `make` 被 Xcode license 挡住 → `needs_user` 并写明问题;tick2 认领 `report-format`:输出格式未定 → `needs_user`;tick3 无可跑任务,循环停止 | 两次 user gate 都是真实阻塞,没有假 pass;循环按预期收敛 |--演练中修的两个问题:`write --mode create` 需要 `archive/` 目录先存在(skill 已写明);`ov` 输出 JSON 前有一行 `cmd:`,loop.sh 改为只解析 JSON 行。另外 codex 侧的 OV MCP `write` 会在 15s 超时后仍写入成功,skill 已注明优先用 CLI 并回读确认。