@sma1lboy/kobe 0.8.192 → 0.8.194

package/dist/skills/rove/SKILL.md

@@ -3,7 +3,7 @@ name: rove
 description: Use when controlling Rove tasks, parallel coding attempts, hosted agent sessions, task lifecycle, or the daemon-owned issue tracker from a shell. Also the ONLY channel for messaging another agent session on this machine — `rove api send`, never a peer/MCP side channel.
 ---
 
-<!-- rove-skill-version: 32 — bump in lockstep with KOBE_SKILL_VERSION (src/lib/skill-install.ts). -->
+<!-- rove-skill-version: 33 — bump in lockstep with KOBE_SKILL_VERSION (src/lib/skill-install.ts). -->
 
 # Rove shell control
 
@@ -208,15 +208,35 @@ build artifacts, nothing a lockfile promises. Two consequences:
 
 ## Discover before calling
 
+Do not guess flags — but do not pay a round-trip for the ones you use every
+turn either. These five carry almost all traffic:
+
+```text
+add      --repo(REQ) --prompt --title --command --count --agents --activate
+send     --prompt(REQ) --task-id --tab --command --plain
+get-task --task-id(REQ)          list  (no flags)
+collect  --task-ids <csv> | --repo
+```
+
+Four names that have actually been guessed wrong here: `add --vendor` is
+`--command`; `read-output --task` is `--task-id`; `dispatch --text` is
+`--prompt` (`--text` belongs to `note`); `issue-list` has no `--state` at all
+— filter its JSON yourself.
+
+**[`references/api-flags.md`](references/api-flags.md) is every verb and flag**,
+including the groups this file leaves out on purpose: `routine-*` (scheduled
+prompts), `workitem-*` (GitHub issues via `gh`), `note`/`note-list` (the repo's
+durable field-note store), `read-output`/`digest`/`agent-turns`/`pty-list`, and
+the error-code table. Read it when you need a verb that is not above; reach for
+`schema` when the binary and that file disagree.
+
 ```bash
-rove api schema
-rove api schema --verb add
-rove api schema --group create
+rove api schema --verb add    # or --group create, --all
 rove api <verb> --help
 rove api engine-list          # what you can launch, and with what command
 ```
 
-Do not guess flags. Commands emit one JSON object; errors use
+Commands emit one JSON object; errors use
 `{"error":{"message","code",...}}` on stderr. Common rejections also carry
 `hint` (what to do) and `nextCommandArgs` (argv for the same `Rove`
 executable — run `rove <args...>` verbatim to recover, e.g. `["api","list"]`
@@ -267,7 +287,8 @@ auto-start the canonical engine in the task's worktree (`started: true` in
 the result marks that fresh session). If live tabs exist but none resolves
 as an engine, it refuses with `NO_ENGINE_TAB` — address one with `--tab
 tab-N` or spawn one with `--tab new`; it never silently spawns a duplicate
-engine.
+engine. Its `hint` names `pty-list` — the live-PTY read (key, alive, pid,
+command); use it when `.tabs[]` and reality disagree.
 
 ## Terminal panes
 

package/dist/skills/rove/references/api-flags.md

@@ -0,0 +1,223 @@
+# `rove api` flag reference
+
+Every verb and flag, so you don't pay a `schema` round-trip to look one up.
+SKILL.md covers the verbs you need for routing and lifecycle; this file is the
+full surface, including the groups SKILL.md deliberately leaves out
+(routines, GitHub work items, telemetry reads, field notes).
+
+Authoritative source is still the binary — `rove api schema --verb <name>` or
+`rove api <verb> --help`. Read that when this file and a rejection disagree;
+the CLI is what ships.
+
+Global: `--pretty` (readable JSON), `--help` (usage, exit).
+Every `--repo` resolves relative paths against `$PWD` and wants the git toplevel.
+
+## The hot path
+
+These five carry almost all traffic. Nothing here should ever need `schema`.
+
+```text
+add     --repo(REQ) --prompt --title --command --count --agents
+        --branch --base-branch --status --pin --activate
+send    --prompt(REQ) --task-id --tab --command --plain
+get-task --task-id(REQ)
+list    (no flags)
+collect --task-ids <csv> | --repo
+```
+
+Four flag names that have actually been guessed wrong here, and what they are:
+
+| Guessed | Real |
+|---|---|
+| `add --vendor` | `add --command` (engine id or full command line) |
+| `read-output --task` | `read-output --task-id` |
+| `dispatch --text` | `dispatch --prompt` (`--text` belongs to `note`) |
+| `issue-list --state` | none — `issue-list` takes only `--repo`; filter the JSON yourself |
+
+`--count`/`--agents` require `--prompt`. `--branch` is single-task only.
+`--tab new` is the only placement that accepts `send --command`.
+
+## Retired — these no longer exist
+
+| Gone | Now |
+|---|---|
+| `fan-out` | `add --count N` / `add --agents claude:2,codex:1` |
+| `task-list` | `list` |
+| `send-tab` | `send --tab tab-N` |
+| `$KOBE_TASK_ID` / `$KOBE_TAB_ID` | `$ROVE_TASK_ID` / `$ROVE_TAB_ID` |
+
+Seeing one of these in guidance means that guidance predates the rename —
+`rove api schema` is the tiebreak.
+
+## read
+
+```text
+list          (none)                     every task, archived included
+get-task      --task-id(REQ)             one task + .tabs[] — the read before `send --tab`
+collect       --task-ids <csv> --repo    comparison snapshot across tasks
+inspect       --task-id                  daemon activity + pty walk + tab snapshots
+pty-list      (none)                     live hosted PTYs: key, alive, pid, command, OSC title
+read-output   --task-id --tab --source[auto|history|terminal] --cursor --limit
+digest        --repo(REQ) --since-days(7)
+agent-turns   --task-id --repo --since-days(7) --limit(200)
+```
+
+`pty-list` is what `NO_ENGINE_TAB`'s hint points at: when `.tabs[]` and reality
+disagree, it is the ground truth for what is actually alive.
+
+`read-output --limit` maxes at 50 (default 40). `--tab` is terminal-only —
+it cannot combine with `--source history`. The cursor is pinned to one
+source/session/tab; a moved target returns `SOURCE_CHANGED` rather than
+silently paging something else.
+
+`digest` and `agent-turns` are the measurement reads — `digest` aggregates a
+repo's recent task + routine activity, `agent-turns` is per-turn telemetry
+(vendor, model, timings, tokens). Reach for them when a workflow question
+needs numbers, not when you want to know what a task is doing.
+
+## drive
+
+```text
+send        --prompt(REQ) --task-id --tab --command --plain
+dispatch    --task-id(REQ) --prompt(REQ) --tab
+note        --task-id(REQ) --text(REQ)
+note-list   --repo(REQ)
+pane-open   --command --task-id --tab --direction[right|down] --placement[split|tab] --title
+pane-close  --title(REQ) --task-id --tab
+notify      --title(REQ) --kind --task-id --source
+prompt      --title(REQ) --placeholder --initial --timeout
+set-active  --task-id | --none
+```
+
+**`note` is the repo's durable field-note store.** One line, a verified
+conclusion another session could act on — it is appended to the repo's notes
+(every future session on this repo starts with them) AND relayed to the
+dispatcher. Read them back with `note-list --repo`. This is the right home for
+a resolved gotcha; an issue is for work that still needs doing.
+
+`notify --kind` styles the toast: `done`, `needs_input`, `error` get severity
+treatment and an unread mark, anything else renders neutrally.
+
+`prompt` blocks on a human answering the attached TUI's input dialog —
+`--timeout` defaults to 120000ms, caps at 600000. Returns `{ value }` or
+`{ cancelled, reason }`. No attached TUI means no answer.
+
+`pane-open --command` runs through the login shell's `-ilc`, so pipes and
+your rc's PATH work.
+
+## create / edit / lifecycle
+
+```text
+add            --repo(REQ) + the hot-path flags above
+rename         --task-id(REQ) --title(REQ)
+set-branch     --task-id(REQ) --branch(REQ)
+set-command    --task-id(REQ) --command(REQ)      next launch only
+set-status     --task-id(REQ) --status(REQ)[backlog|in_progress|in_review|done|canceled|error]
+archive        --task-id(REQ) --archived(true)
+pin            --task-id(REQ) --pinned(true)
+land           --task-id(REQ) --strategy[merge|squash] --delete-branch --then-archive --remove-worktree
+delete         --task-id(REQ) --force --delete-branch
+```
+
+Task `--status` and issue `--status` are DIFFERENT enums — a task is
+`backlog|in_progress|in_review|done|canceled|error`, an issue is
+`open|doing|hold|done`.
+
+`land` refuses a dirty base checkout and refuses a branch with zero commits
+ahead (`EMPTY_BRANCH`; `EMPTY_BRANCH_DIRTY_WORKTREE` when the worktree still
+holds the uncommitted work, with a send-back recovery path). Conflict aborts
+cleanly and returns the conflicted files.
+
+## worktree
+
+```text
+ensure-worktree      --task-id(REQ)
+discover-adoptable   --repo(REQ)
+adopt                --repo(REQ) --worktree(REQ) --branch --title --command
+```
+
+## issues (daemon-owned)
+
+```text
+issue-list        --repo(REQ)
+issue-create      --repo(REQ) --title(REQ) --body
+issue-update      --repo(REQ) --id(REQ,int) --title --body --task
+issue-set-status  --repo(REQ) --id(REQ,int) --status(REQ)[open|doing|hold|done]
+```
+
+`--id` is an int, not the ULID a task uses. `issue-update --task <taskId>` is
+the kanban "move to In progress"; `--task none` unlinks. Kanban semantics are
+in SKILL.md — do not move cards with `issue-set-status doing`.
+
+## workitems (GitHub, through `gh`)
+
+Read-only against the repo's real GitHub issues; nothing is copied into Rove's
+own store. These are the INBOUND user reports; Rove issues are the backlog.
+
+```text
+workitem-list   --repo(REQ) --state[open|closed|all] --limit(20,max 50) --search --assignee --label
+workitem-start  --repo(REQ) --number(REQ,int) --vendor --base-branch
+```
+
+`workitem-start` creates a worktree + engine whose first message carries the
+issue title, body, and URL, and keeps a link back to the issue. Note it takes
+`--vendor` (an engine enum), not `--command` — the one place the older
+vocabulary survives.
+
+## routines (scheduled prompts)
+
+Each firing creates a FRESH task — worktree, engine, delivered prompt. An
+enabled routine holds the daemon alive so it fires with no TUI attached.
+
+```text
+routine-list         (none)
+routine-create       --repo(REQ) --name(REQ) --prompt(REQ) --schedule(REQ)
+                     --vendor --base-branch --precheck --precheck-timeout(120) --grace(60) --disabled
+routine-update       --id(REQ) --name --prompt --schedule --vendor --base-branch --precheck --precheck-timeout --grace
+routine-set-enabled  --id(REQ) --enabled(REQ,bool)
+routine-delete       --id(REQ)
+routine-run-now      --id(REQ)
+routine-runs         --id(REQ)
+```
+
+`--schedule` is five-field cron in the DAEMON HOST's local time
+(`'0 9 * * MON-FRI'`). `--precheck` is a shell command run in the repo before
+the engine starts — non-zero exit skips the run without spawning an agent,
+which is the cheap way to not burn a turn on "nothing to do". `--grace` is how
+late a missed occurrence may still run after the daemon was down; only the
+most recent missed occurrence ever runs.
+
+`routine-update --schedule` re-anchors the next run. `--precheck ''` clears it.
+`routine-run-now` skips the precheck deliberately (asking for it IS the answer)
+and does not shift the schedule. `routine-delete` leaves already-created tasks
+alone.
+
+Run statuses from `routine-runs`: `dispatched`, `skipped_precheck` (nothing to
+do), `skipped_missed`, `skipped_unavailable`, `dispatch_failed`.
+
+## discover / feedback
+
+```text
+schema        --verb <name> | --group <g> | --all      (bare = compact index)
+engine-list   (none)                                   ids + RAW launch command + protocol
+feedback      --title(REQ) --body(REQ) --category(feedback)
+```
+
+`feedback` opens a GitHub Discussion in the Rove repo through `gh` — Rove's own
+product feedback channel, not a way to file work for another project (that is
+a `send` to their main task; see SKILL.md).
+
+## Error codes
+
+Errors go to stderr as `{"error":{"message","code",...}}`. Most carry `hint`
+(what to do) and `nextCommandArgs` (argv for the same executable — run
+`rove <args...>` verbatim).
+
+| Code | Means | Recover |
+|---|---|---|
+| `BAD_FLAG` | flag not on that verb | check the table above, then `schema --verb <v>` |
+| `TASK_NOT_FOUND` | id deleted or mistyped | `rove api list` |
+| `NO_ENGINE_TAB` | live tabs exist, none is an engine | `--tab tab-N` from `pty-list`, or `--tab new` |
+| `DISPATCHER_UNREACHABLE` | bare `send` reply, dispatcher gone | nothing alive to reply to — never silently spawns |
+| `SOURCE_CHANGED` | `read-output` cursor's target moved | re-read without the cursor |
+| `EMPTY_BRANCH` | `land` on zero commits ahead | the worker committed nothing |

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@sma1lboy/kobe",
-  "version": "0.8.192",
+  "version": "0.8.194",
   "description": "Rove — the agent multiplexer for your terminal. Run coding agents on parallel tasks with isolated worktrees and persistent sessions.",
   "type": "module",
   "packageManager": "bun@1.3.13",