mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-05-05 02:31:47 +00:00
docs(kanban): backfill multi-board refs in reference docs (#19704)
Followup to #19653. The feature PR updated the Kanban user guide but missed four other pages that document the same surface. Caught when Teknium asked 'did you add docs to the guide and any other kanban related docs around this?'. - reference/cli-commands.md: rewrite the `hermes kanban` section to document the `--board <slug>` global flag, the `boards` subcommand group (list/create/switch/show/rename/rm), board resolution order, and worked examples. Also fills in the `create` / `complete` flag lists that had drifted from the current CLI (`--summary`, `--metadata`, `--triage`, `--idempotency-key`, `--max-runtime`, `--skill`). - reference/environment-variables.md: add `HERMES_KANBAN_BOARD` row, update `HERMES_KANBAN_DB` precedence note. - reference/slash-commands.md: add `/kanban boards ...` and `/kanban --board <slug> ...` to the two `/kanban` rows (CLI table + gateway table). - features/kanban-tutorial.md: the walkthrough uses the `default` board, so just a note pointing readers at the overview's Boards section if they want multiple queues, plus the corrected per-board DB path. Skill docs (devops-kanban-orchestrator, -worker) intentionally not updated: those are agent-facing lifecycle playbooks and boards are transparent to workers (HERMES_KANBAN_BOARD env var pins the DB automatically), so there's nothing new for a worker to know.
This commit is contained in:
Teknium
GitHub
parent
a8b689f0c2
commit
b2b479b40e
4 changed files with 46 additions and 13 deletions
|
|
@ -340,34 +340,64 @@ hermes cron <list|create|edit|pause|resume|run|remove|status|tick>
|
|||
## `hermes kanban`
|
||||
|
||||
```bash
|
||||
hermes kanban <action> [options]
|
||||
hermes kanban [--board <slug>] <action> [options]
|
||||
```
|
||||
|
||||
Multi-profile collaboration board. Tasks live in `~/.hermes/kanban.db` (WAL-mode SQLite); every profile reads and writes the same board. A `cron`-driven dispatcher (`hermes kanban dispatch`) atomically claims ready tasks and spawns the assigned profile as its own process with an isolated workspace.
|
||||
Multi-profile, multi-project collaboration board. Each install can host many boards (one per project, repo, or domain); each board is a standalone queue with its own SQLite DB and dispatcher scope. New installs start with one board called `default`, whose DB is `~/.hermes/kanban.db` for back-compat; additional boards live at `~/.hermes/kanban/boards/<slug>/kanban.db`. The gateway-embedded dispatcher sweeps every board per tick.
|
||||
|
||||
**This is the human / scripting surface.** Agent workers spawned by the dispatcher drive the board through a dedicated `kanban_*` [toolset](/docs/user-guide/features/kanban#how-workers-interact-with-the-board) (`kanban_show`, `kanban_complete`, `kanban_block`, `kanban_create`, `kanban_link`, `kanban_comment`, `kanban_heartbeat`) instead of shelling to `hermes kanban`. Both surfaces route through the same `kanban_db` layer, so state is consistent either way.
|
||||
**Global flags (apply to every action below):**
|
||||
|
||||
| Flag | Purpose |
|
||||
|------|---------|
|
||||
| `--board <slug>` | Operate on a specific board. Defaults to the current board (set via `hermes kanban boards switch`, the `HERMES_KANBAN_BOARD` env var, or `default`). |
|
||||
|
||||
**This is the human / scripting surface.** Agent workers spawned by the dispatcher drive the board through a dedicated `kanban_*` [toolset](/docs/user-guide/features/kanban#how-workers-interact-with-the-board) (`kanban_show`, `kanban_complete`, `kanban_block`, `kanban_create`, `kanban_link`, `kanban_comment`, `kanban_heartbeat`) instead of shelling to `hermes kanban`. Workers have `HERMES_KANBAN_BOARD` pinned in their env so they physically cannot see other boards.
|
||||
|
||||
| Action | Purpose |
|
||||
|--------|---------|
|
||||
| `init` | Create `kanban.db` if missing. Idempotent. |
|
||||
| `create "<title>"` | Create a new task. Flags: `--body`, `--assignee`, `--parent` (repeatable), `--workspace scratch\|worktree\|dir:<path>`, `--tenant`, `--priority`. |
|
||||
| `list` / `ls` | List tasks. Filter with `--mine`, `--assignee`, `--status`, `--tenant`, `--archived`, `--json`. |
|
||||
| `boards list` / `boards ls` | List all boards with task counts. `--json`, `--all` (include archived). |
|
||||
| `boards create <slug>` | Create a new board. Flags: `--name`, `--description`, `--icon`, `--color`, `--switch` (make active). Slug is kebab-case, auto-downcased. |
|
||||
| `boards switch <slug>` / `boards use` | Persist `<slug>` as the active board (writes `~/.hermes/kanban/current`). |
|
||||
| `boards show` / `boards current` | Print the currently-active board's name, DB path, and task counts. |
|
||||
| `boards rename <slug> "<name>"` | Change a board's display name. Slug is immutable. |
|
||||
| `boards rm <slug>` | Archive (default) or hard-delete a board. `--delete` skips the archive step. Archived boards move to `boards/_archived/<slug>-<ts>/`. Refused for `default`. |
|
||||
| `create "<title>"` | Create a new task on the active board. Flags: `--body`, `--assignee`, `--parent` (repeatable), `--workspace scratch\|worktree\|dir:<path>`, `--tenant`, `--priority`, `--triage`, `--idempotency-key`, `--max-runtime`, `--skill` (repeatable). |
|
||||
| `list` / `ls` | List tasks on the active board. Filter with `--mine`, `--assignee`, `--status`, `--tenant`, `--archived`, `--json`. |
|
||||
| `show <id>` | Show a task with comments and events. `--json` for machine output. |
|
||||
| `assign <id> <profile>` | Assign or reassign. Use `none` to unassign. Refused while task is running. |
|
||||
| `link <parent> <child>` | Add a dependency. Cycle-detected. |
|
||||
| `link <parent> <child>` | Add a dependency. Cycle-detected. Both tasks must be on the same board. |
|
||||
| `unlink <parent> <child>` | Remove a dependency. |
|
||||
| `claim <id>` | Atomically claim a ready task. Prints resolved workspace path. |
|
||||
| `comment <id> "<text>"` | Append a comment. The next worker that claims the task reads it as part of its `kanban_show()` response. |
|
||||
| `complete <id>` | Mark task done. Flag: `--result "<summary>"` (goes into children's parent-result context). |
|
||||
| `complete <id>` | Mark task done. Flags: `--result`, `--summary`, `--metadata`. |
|
||||
| `block <id> "<reason>"` | Mark task blocked. Also appends the reason as a comment. |
|
||||
| `unblock <id>` | Return a blocked task to ready. |
|
||||
| `archive <id>` | Hide from default list. `gc` will remove scratch workspaces. |
|
||||
| `tail <id>` | Follow a task's event stream. |
|
||||
| `dispatch` | One dispatcher pass. Flags: `--dry-run`, `--max N`, `--json`. |
|
||||
| `dispatch` | One dispatcher pass on the active board. Flags: `--dry-run`, `--max N`, `--json`. |
|
||||
| `context <id>` | Print the full context a worker would see (title + body + parent results + comments). |
|
||||
| `gc` | Remove scratch workspaces for archived tasks. |
|
||||
|
||||
All actions are also available as a slash command in the gateway (`/kanban …`), with the same argument surface.
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# Create a second board and put a task on it without switching away.
|
||||
hermes kanban boards create atm10-server --name "ATM10 Server" --icon 🎮
|
||||
hermes kanban --board atm10-server create "Restart server" --assignee ops
|
||||
|
||||
# Switch the active board for subsequent calls.
|
||||
hermes kanban boards switch atm10-server
|
||||
hermes kanban list # shows atm10-server tasks
|
||||
|
||||
# Archive a board (recoverable) or hard-delete it.
|
||||
hermes kanban boards rm atm10-server
|
||||
hermes kanban boards rm atm10-server --delete
|
||||
```
|
||||
|
||||
Board resolution order (highest precedence first): `--board <slug>` flag → `HERMES_KANBAN_BOARD` env var → `~/.hermes/kanban/current` file → `default`.
|
||||
|
||||
All actions are also available as a slash command in the gateway (`/kanban …`), with the same argument surface — including `boards` subcommands and the `--board` flag.
|
||||
|
||||
For the full design — comparison with Cline Kanban / Paperclip / NanoClaw / Gemini Enterprise, eight collaboration patterns, four user stories, concurrency correctness proof — see `docs/hermes-kanban-v1-spec.pdf` in the repository or the [Kanban user guide](/docs/user-guide/features/kanban).
|
||||
|
||||
|
|
|
|||
|
|
@ -89,7 +89,8 @@ All variables go in `~/.hermes/.env`. You can also set them with `hermes config
|
|||
| `HERMES_LOCAL_STT_LANGUAGE` | Default language passed to `HERMES_LOCAL_STT_COMMAND` or auto-detected local `whisper` CLI fallback (default: `en`) |
|
||||
| `HERMES_HOME` | Override Hermes config directory (default: `~/.hermes`). Also scopes the gateway PID file and systemd service name, so multiple installations can run concurrently |
|
||||
| `HERMES_KANBAN_HOME` | Override the shared Hermes root that anchors the kanban board (db + workspaces + worker logs). Falls back to `get_default_hermes_root()` (the parent of any active profile). Useful for tests and unusual deployments |
|
||||
| `HERMES_KANBAN_DB` | Pin the kanban database file path directly (highest precedence; beats `HERMES_KANBAN_HOME`). The dispatcher injects this into worker subprocess env so profile workers converge on the dispatcher's board |
|
||||
| `HERMES_KANBAN_BOARD` | Pin the active kanban board for this process. Takes precedence over `~/.hermes/kanban/current`; the dispatcher injects this into worker subprocess env so workers physically cannot see tasks on other boards. Defaults to `default`. Slug validation: lowercase alphanumerics + hyphens + underscores, 1-64 chars |
|
||||
| `HERMES_KANBAN_DB` | Pin the kanban database file path directly (highest precedence; beats `HERMES_KANBAN_BOARD` and `HERMES_KANBAN_HOME`). The dispatcher injects this into worker subprocess env so profile workers converge on the dispatcher's board |
|
||||
| `HERMES_KANBAN_WORKSPACES_ROOT` | Pin the kanban workspaces root directly (highest precedence for workspaces; beats `HERMES_KANBAN_HOME`). The dispatcher injects this into worker subprocess env |
|
||||
|
||||
## Provider Auth (OAuth)
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
|
|||
| `/skills` | Search, install, inspect, or manage skills from online registries |
|
||||
| `/cron` | Manage scheduled tasks (list, add/create, edit, pause, resume, run, remove) |
|
||||
| `/curator` | Background skill maintenance — `status`, `run`, `pin`, `archive`. See [Curator](/docs/user-guide/features/curator). |
|
||||
| `/kanban <action>` | Drive the multi-profile collaboration board without leaving chat. Full `hermes kanban` surface is available: `/kanban list`, `/kanban show t_abc`, `/kanban create "title" --assignee X`, `/kanban comment t_abc "text"`, `/kanban unblock t_abc`, `/kanban dispatch`, etc. See [Kanban slash command](/docs/user-guide/features/kanban#kanban-slash-command). |
|
||||
| `/kanban <action>` | Drive the multi-profile, multi-project collaboration board without leaving chat. Full `hermes kanban` surface is available: `/kanban list`, `/kanban show t_abc`, `/kanban create "title" --assignee X`, `/kanban comment t_abc "text"`, `/kanban unblock t_abc`, `/kanban dispatch`, etc. Multi-board support included: `/kanban boards list`, `/kanban boards create <slug>`, `/kanban boards switch <slug>`, `/kanban --board <slug> <action>`. See [Kanban slash command](/docs/user-guide/features/kanban#kanban-slash-command). |
|
||||
| `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config.yaml |
|
||||
| `/reload` | Reload `.env` variables into the running session (picks up new API keys without restarting) |
|
||||
| `/plugins` | List installed plugins and their status |
|
||||
|
|
@ -158,7 +158,7 @@ The messaging gateway supports the following built-in commands inside Telegram,
|
|||
| `/goal <text>` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. A judge model checks after each turn; if not done, Hermes auto-continues until it is, you pause/clear it, or the turn budget (default 20) is hit. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Safe to run mid-agent for status/pause/clear; setting a new goal requires `/stop` first. See [Persistent Goals](/docs/user-guide/features/goals). |
|
||||
| `/footer [on\|off\|status]` | Toggle the runtime-metadata footer on final replies (shows model, tool counts, timing). |
|
||||
| `/curator [status\|run\|pin\|archive]` | Background skill maintenance controls. |
|
||||
| `/kanban <action>` | Drive the multi-profile collaboration board from chat — identical argument surface to the CLI. Bypasses the running-agent guard, so `/kanban unblock t_abc`, `/kanban comment t_abc "…"`, `/kanban list --mine`, etc. work mid-turn. `/kanban create …` auto-subscribes the originating chat to the new task's terminal events. See [Kanban slash command](/docs/user-guide/features/kanban#kanban-slash-command). |
|
||||
| `/kanban <action>` | Drive the multi-profile, multi-project collaboration board from chat — identical argument surface to the CLI. Bypasses the running-agent guard, so `/kanban unblock t_abc`, `/kanban comment t_abc "…"`, `/kanban list --mine`, `/kanban boards switch <slug>`, etc. work mid-turn. `/kanban create …` auto-subscribes the originating chat to the new task's terminal events. See [Kanban slash command](/docs/user-guide/features/kanban#kanban-slash-command). |
|
||||
| `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config. |
|
||||
| `/yolo` | Toggle YOLO mode — skip all dangerous command approval prompts. |
|
||||
| `/commands [page]` | Browse all commands and skills (paginated). |
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue