3 Commits

Author	SHA1	Message	Date
Teknium	b2b479b40e	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.	2026-05-04 04:47:19 -07:00
Teknium	986ec04048	docs: document /kanban slash command (#19584) ... * docs: document /kanban slash command The kanban user guide and slash-commands reference only mentioned the /kanban slash command in passing. Add a proper section covering: - CLI and gateway both expose the full hermes kanban surface via hermes_cli.kanban.run_slash (identical argument surface) - Mid-run usage: /kanban bypasses the running-agent guard, so reads and writes land immediately while an agent is still in a turn - Auto-subscribe on /kanban create from the gateway — originating chat is subscribed to terminal events, with a worked example - Output truncation (~3800 chars) in messaging - Autocomplete hint list vs full subcommand surface Also adds /kanban rows to both slash-command tables (CLI + messaging) in reference/slash-commands.md and moves it into the 'works in both' notes bucket. * docs(kanban): frame the model's tool surface as primary, CLI as the human surface The kanban user guide and CLI reference read as if you drive the board by running `hermes kanban` commands everywhere. In practice: - **You** (human, scripts, cron, dashboard) use the `hermes kanban …` CLI, the `/kanban …` slash command, or the REST/dashboard. - **Workers** spawned by the dispatcher use a dedicated `kanban_*` toolset (`kanban_show`, `kanban_complete`, `kanban_block`, `kanban_heartbeat`, `kanban_comment`, `kanban_create`, `kanban_link`) and never shell out to the CLI. Changes to `user-guide/features/kanban.md`: - New 'Two surfaces' intro distinguishes the two front doors up front. - Quick-start section re-labelled so each step says who is running it (you vs. orchestrator vs. worker). - 'How workers interact with the board' rewritten: - Lead with "Workers do not shell out to `hermes kanban`." - Tool table extended with required params. - Concrete worker-turn example (`kanban_show` → `kanban_heartbeat` → `kanban_complete`) and an orchestrator fan-out example (`kanban_create` x N with `parents=[...]`). - Moved 'Why tools not CLI' from a defensive aside to a clean follow-up section. - 'Worker skill' section explicitly says the lifecycle is taught in tool calls, not CLI commands. - 'Pinning extra skills' reordered — orchestrator tool form first (the usual case), human/CLI second, dashboard third. - 'Orchestrator skill' now shows a canonical `kanban_create` / `kanban_link` / `kanban_complete` tool-call sequence instead of only describing what the skill teaches. - CLI-command-reference heading now clarifies this is the human surface, with a cross-link to the tool-surface section. - 'Runs — one row per attempt' structured-handoff example replaced: the primary example is now `kanban_complete(summary=..., metadata=...)` (what a worker actually does), with the CLI form retained as "when you, the human, need to close a task a worker can't." Changes to `reference/cli-commands.md`: - `hermes kanban` intro marks itself as the human / scripting surface and links out to the worker tool surface. - Corrected `comment <id>` description — the next worker reads it via `kanban_show()`, not by running `hermes kanban show`. * docs(kanban-tutorial): reframe worker actions as tool calls Honest answer to Teknium's follow-up: no, the first pass missed the tutorial. The four stories all showed `hermes kanban claim / complete / block / unblock` as if the backend-dev, pm, and reviewer personas were humans running CLI commands. In a real hermes kanban run those agents are dispatcher-spawned workers driving the board through the `kanban_*` tool surface. Changes: - Setup intro now distinguishes the three surfaces up front (dashboard / CLI for you, `kanban_*` tools for workers) and establishes the convention: `bash` blocks are commands *you* run, `# worker tool calls` blocks are what the agent emits. - Story 1 (solo dev schema): 'Claim the schema task, do the work, hand off' block replaced with the dispatcher spawning the backend-dev worker and a `kanban_show → kanban_heartbeat → kanban_complete` tool-call sequence. The 'On the CLI' `hermes kanban show / runs` block re-labelled as 'you peeking at the board' to keep it correct as a human inspection step. - Story 2 (fleet farming): note about structured handoff updated from `--summary` / `--metadata` CLI flags to `kanban_complete(summary=..., metadata=...)` tool form. - Story 3 (role pipeline): the big PM/engineer/reviewer block fully rewritten as three worker tool-call sequences — PM worker completes spec, engineer worker blocks, human/reviewer `hermes kanban unblock` (or `/kanban unblock`), engineer worker respawns and completes. The respawn-as-new-run mechanic is now explicit. - Reviewer paragraph: `build_worker_context` replaced with `kanban_show()` — that's the tool that delivers the parent handoff to the model. - Structured handoff section heading and body updated: `--summary`/`--metadata` → `summary`/`metadata` (tool params), with a note that the tool surface doesn't expose a bulk variant for the same reason the CLI refuses multi-task `complete`. Story 4 (circuit breaker) unchanged — its workers fail to spawn, so there are no tool calls to show; the `hermes kanban create` and `hermes kanban runs` commands in it are correctly human-driven.	2026-05-04 03:05:34 -07:00
Teknium	c868425467	feat(kanban): durable multi-profile collaboration board (#17805) ... Salvage of PR #16100 onto current main (after emozilla's #17514 fix that unblocks plugin Pydantic body validation). History preserved on the standing `feat/kanban-standing` branch; this squashes the 22 iterative commits into one clean landing. What this lands: - SQLite kernel (hermes_cli/kanban_db.py) — durable task board with tasks, task_links, task_runs, task_comments, task_events, kanban_notify_subs tables. WAL mode, atomic claim via CAS, tenant-namespaced, skills JSON array per task, max-runtime timeouts, worker heartbeats, idempotency keys, circuit breaker on repeated spawn failures, crash detection via /proc/<pid>/status, run history preserved across attempts. - Dispatcher — runs inside the gateway by default (`kanban.dispatch_in_gateway: true`). Ticks every 60s, reclaims stale claims, promotes ready tasks, spawns `hermes -p <assignee> chat -q "work kanban task <id>"` with HERMES_KANBAN_TASK + HERMES_KANBAN_WORKSPACE env. Auto-loads `--skills kanban-worker` plus any per-task skills. Health telemetry warns on stuck ready queue. - Structured tool surface (tools/kanban_tools.py) — 7 tools (kanban_show, kanban_complete, kanban_block, kanban_heartbeat, kanban_comment, kanban_create, kanban_link). Gated on HERMES_KANBAN_TASK via check_fn so zero schema footprint in normal sessions. - System-prompt guidance (agent/prompt_builder.py KANBAN_GUIDANCE) injected only when kanban tools are active. - Dashboard plugin (plugins/kanban/dashboard/) — Linear-style board UI: triage/todo/ready/running/blocked/done columns, drag-drop, inline create, task drawer with markdown, comments, run history, dependency editor, bulk ops, lanes-by-profile grouping, WS-driven live refresh. Matches active dashboard theme via CSS variables. - CLI — `hermes kanban init|create|list|show|assign|link|unlink| claim|comment|complete|block|unblock|archive|tail|dispatch|context| init|gc|watch|stats|notify|log|heartbeat|runs|assignees` + `/kanban` slash in-session. - Worker + orchestrator skills (skills/devops/kanban-worker + kanban-orchestrator) — pattern library for good summary/metadata shapes, retry diagnostics, block-reason examples, fan-out patterns. - Per-task force-loaded skills — `--skill <name>` (repeatable), stored as JSON, threaded through to dispatcher argv as one `--skills X` pair per skill alongside the built-in kanban-worker. Dashboard + CLI + tool parity. - Deprecation of standalone `hermes kanban daemon` — stub exits 2 with migration guidance; `--force` escape hatch for headless hosts. - Docs (website/docs/user-guide/features/kanban.md + kanban-tutorial.md) with 11 dashboard screenshots walking through four user stories (Solo Dev, Fleet Farming, Role Pipeline, Circuit Breaker). - Tests (251 passing): kernel schema + migration + CAS atomicity, dispatcher logic, circuit breaker, crash detection, max-runtime timeouts, claim lifecycle, tenant isolation, idempotency keys, per- task skills round-trip + validation + dispatcher argv, tool surface (7 tools × round-trip + error paths), dashboard REST (CRUD + bulk + links + warnings), gateway-embedded dispatcher (config gate, env override, graceful shutdown), CLI deprecation stub, migration from legacy schemas. Gateway integration: - GatewayRunner._kanban_dispatcher_watcher — new asyncio background task, symmetric with _kanban_notifier_watcher. Runs dispatch_once via asyncio.to_thread so SQLite WAL never blocks the loop. Sleeps in 1s slices for snappy shutdown. Respects HERMES_KANBAN_DISPATCH_IN_GATEWAY=0 env override for debugging. - Config: new `kanban` section in DEFAULT_CONFIG with `dispatch_in_gateway: true` (default) + `dispatch_interval_seconds: 60`. Additive — no \_config_version bump needed. Forward-compat: - workflow_template_id / current_step_key columns on tasks (v1 writes NULL; v2 will use them for routing). - task_runs holds claim machinery (claim_lock, claim_expires, worker_pid, last_heartbeat_at) so multi-attempt history is first- class from day one. Closes #16102. Co-authored-by: emozilla <emozilla@nousresearch.com>	2026-04-30 13:36:47 -07:00