All plugins

kanban-empowered

A redesign for the Hermes kanban: per-board project status, a dashboard that explains what is really happening across your boards, a live summary of what each agent is doing right now, a chain view that shows where a block starts, and a fast way to answer what the kanban needs from you, by Telegram or Desktop. Cards waiting on a person get a structured ask, reminders and an escalation; cards held by guards or parked by host failures are reported or undone within a budget. No card stays silently stuck. Disclosure β€” a coordinator runs inside the gateway's kanban dispatch tick (coordinator profile only, leader lock, no extra process); it reads every board's kanban database and metadata through Hermes' kanban functions and writes only through them (comments, unblocking a waiting card when its owner answers, undoing an infrastructure park, reassigning a card on the release command); its SQLite state lives under the coordinator profile's plugin-data/kanban-empowered and is read by the plugin in every other profile, and its doctor command reads every profile's config.yaml read-only; it consumes Telegram replies from the configured owners to its own messages before they reach the agent, except that an owner's answer to a card a worker cannot run is rewritten into an instruction (card title, assignee and the owner's answer) and passed on as a normal turn to the Hermes session of that same chat, reads TELEGRAM_BOT_TOKEN (the gateway's bot) only through Hermes' secret scope, and, apart from the auxiliary model below, calls only the Telegram Bot API (sendMessage, editMessageText, pinChatMessage to the configured owner chats, one pinned panel; never getUpdates) plus Hermes' own IPv4 fallback path (DNS-over-HTTPS lookups of api.telegram.org at dns.google and cloudflare-dns.com); to show what a running card is doing, the Desktop backend reads that worker's recent session from its profile's state.db read-only (what the agent wrote, including reasoning, and tool names; never commands or tool output), redacts secrets and sends it to the Hermes auxiliary model the user configured, only when the session changed and at most once a minute per card; when the user asks to explain a project's blocks, it also sends that project's waiting cards (titles, block reasons, options and counts, already redacted; no sessions, comments or command output) to the same auxiliary model; no shell commands and no telemetry; imports private Hermes kanban, i18n, profile, plugin and Telegram-network modules (listed in its README); ships an optional core patch adding kanban veto hooks that the user applies by hand to the Hermes checkout (the plugin never applies it, and hermes update drops it), and registers kanban_pre_claim only on a Hermes build that exposes it.

dellanio10Automationv0.4.0Updated 9 days ago

About

A redesign for the Hermes kanban: per-board project status, a dashboard that explains what is really happening across your boards, a live summary of what each agent is doing right now, a chain view that shows where a block starts, and a fast way to answer what the kanban needs from you, by Telegram or Desktop. Cards waiting on a person get a structured ask, reminders and an escalation; cards held by guards or parked by host failures are reported or undone within a budget. No card stays silently stuck. Disclosure β€” a coordinator runs inside the gateway's kanban dispatch tick (coordinator profile only, leader lock, no extra process); it reads every board's kanban database and metadata through Hermes' kanban functions and writes only through them (comments, unblocking a waiting card when its owner answers, undoing an infrastructure park, reassigning a card on the release command); its SQLite state lives under the coordinator profile's plugin-data/kanban-empowered and is read by the plugin in every other profile, and its doctor command reads every profile's config.yaml read-only; it consumes Telegram replies from the configured owners to its own messages before they reach the agent, except that an owner's answer to a card a worker cannot run is rewritten into an instruction (card title, assignee and the owner's answer) and passed on as a normal turn to the Hermes session of that same chat, reads TELEGRAM_BOT_TOKEN (the gateway's bot) only through Hermes' secret scope, and, apart from the auxiliary model below, calls only the Telegram Bot API (sendMessage, editMessageText, pinChatMessage to the configured owner chats, one pinned panel; never getUpdates) plus Hermes' own IPv4 fallback path (DNS-over-HTTPS lookups of api.telegram.org at dns.google and cloudflare-dns.com); to show what a running card is doing, the Desktop backend reads that worker's recent session from its profile's state.db read-only (what the agent wrote, including reasoning, and tool names; never commands or tool output), redacts secrets and sends it to the Hermes auxiliary model the user configured, only when the session changed and at most once a minute per card; when the user asks to explain a project's blocks, it also sends that project's waiting cards (titles, block reasons, options and counts, already redacted; no sessions, comments or command output) to the same auxiliary model; no shell commands and no telemetry; imports private Hermes kanban, i18n, profile, plugin and Telegram-network modules (listed in its README); ships an optional core patch adding kanban veto hooks that the user applies by hand to the Hermes checkout (the plugin never applies it, and hermes update drops it), and registers kanban_pre_claim only on a Hermes build that exposes it.

πŸ—‚οΈ Kanban Empowered

A redesign for the Hermes kanban: clear asks, live status and recovery, so no card stays silently stuck.

Hermes plugin
Version
Python
Telegram
Languages
License

Every board gets its own project status, a dashboard that explains what is happening, a live summary of what each agent is doing, and a one-line way to answer what the kanban needs from you, from Telegram or Desktop.

Kanban Empowered


πŸ’‘ The Problem

Stop digging through card comments to find out what's going on. With a fleet of agent profiles on the Hermes kanban, a card can stop moving for many reasons: it waits on a person who never saw the question, a guard keeps it from respawning, or the host failed and Hermes parked it. Each of these looks the same from the board: a card that silently does not move.


⚑ The Solution: Kanban Empowered

Kanban Empowered gives every board its own project status, a dashboard that actually explains what's happening across your boards, a live plain-language summary of what each agent is doing right now, and a fast way out when the kanban needs you: a clear ask, answered in one line from Telegram or Desktop.

  1. Blocked? It shows you exactly where the block starts and what it's holding back.
  2. Waiting on you? A structured ask, reminders that escalate, and a one-line reply.
  3. Stuck for a technical reason? It fixes what's safe to fix and tells you why about the rest.

No card stays silently stuck.


πŸ“Έ Screenshots

Project map

Pick a project and see every card as a flow, one lane per agent, with the links between them: the card
waiting on you in amber, the running ones in green. By profile orders the cards by dependency;
Timeline places the done ones by the day they finished, then what runs now and what comes next.

The two map images are rendered by the plugin's own desktop/plugin.js and backend from a made-up demo
project; the Desktop's own buttons and icons are approximated.

The rest of the page

Hermes Desktop page (Empowered). Captured from a live install; the sidebar is cropped, private details are blurred and the Portuguese UI text was redrawn in English, so some wording may differ slightly from the app.


✨ Features at a glance

AreaWhat you get
One coordinatorA single process (leader lock) watches every board on Hermes' dispatch tick and owns one shared state, so a fleet of profiles never sends the same reminder twice.
Clear asksA worker that blocks a card on a person must write a structured ask (need, why, how to reply, optional options); a vague block is sent back to the agent to redo.
Reminders that escalate30 min β†’ 2 h β†’ escalation at 8 h β†’ daily digest, with no quiet hours. Ask-less cards are worded from their title, never from technical markers.
Telegram, done properlyBranded [Kanban - Empowered] messages, action-first layout, numbered items, replies tied to the item (1 β€” feito, 2 β€” A, free text), a pinned live panel kept up to date, and a transport that survives a flaky route to api.telegram.org (IPv4 fallback with SNI, sticky last-good path, bounded time).
Stuck-card recoveryRespawn-guard holds reported with a one-line hand-off command; host-only failures parked by Hermes' breaker undone within a budget; a burst of infrastructure exits raises one systemic alert.
Explain everythingexplain <card> lists the conditions that keep a card from moving; status / status --watch show the fleet; doctor checks the whole setup.
Empowered dashboardA Hermes Desktop page (sidebar menu and Kanban header button): counters, Needs you sorted by impact, Running now, the coordinator's timeline, infrastructure health, and a drawer to read the ask and answer it from the desktop.
Project mapPick a project on the dashboard and see its cards as a flow, lane by agent: by dependency level or as a timeline (done by period, now, up next). Up to 100 cards, open ones first; read-only.
Explain a project's blocksNeeds you groups its cards by project; one click asks the Hermes auxiliary model for a plain account of every card of the project that waits on you: what each is stuck on, what to answer or run, and in which order. Commands come with a Copy button.
Project statusMark a board Active, Suspended or Done: suspended projects leave the dashboard's main list, stop getting reminders and have new claims held (via the core veto hook).
Settings screenEvery setting editable from Hermes Desktop (Capabilities / Settings > Plugins).
LanguagesEnglish, pt and pt-br catalogs (parity-tested); follows the Hermes language or a plugin-only override.
Plays niceCoexists with Hermes' own notifier and never repeats its native messages.

Details:

  • Human waits (Telegram). A card blocked on a person gets a reminder after 30 min and 2 h, an
    escalation after 8 h and a daily digest after that. The owner answers the reminder on Telegram,
    naming the item (1 β€” conectei, 3 β€” A, or free text), or runs
    hermes kanban-empowered done <card>, and the card is unblocked.
    When the reminder layout changes in a new plugin version, every open wait is sent once more in
    the new layout (its stage is not advanced). A wait that holds other cards can get its digest on
    its own cadence (waits.blocking_digest_every), and when a wait reaches the escalation with no
    escalate_to configured, the owner gets one setup alert saying so.
  • Cards that only wait on another card. An agent often creates several cards blocked at once and leaves
    one of them for you ("run this script: it unblocks t_72bb187f and archives t_21e0190e"). For Hermes they are
    all the same untyped block. A waiting card whose id another waiting card of the board cites is shown under that
    card ("Unblocks along"), sends no reminder of its own and is not counted (see
    Cards that wait on another card).
  • Requests to another agent. A worker sometimes blocks with a request for another agent of the fleet
    ("Diretor, open a FIX in the collector"). A block whose request opens by addressing one of this installation's
    Hermes profiles is not shown as yours (see Requests addressed to another agent).
  • Cards a worker cannot run. Unblocking a card sends it to a worker of its assignee. When a worker
    cannot run it (it needs your own session, a credential or a CLI the worker is fenced from), the plugin
    does not unblock it: your answer is handed off to an interactive session instead, and the card stays
    blocked (see Handoffs).
  • Stuck cards. Cards held by Hermes' respawn guard (active_pr, blocker_auth) for more than
    30 min are reported to the owner, again every waits.digest while the guard lasts, and listed in
    Needs you with the reason and the last error, with a one-line command to hand them to another profile.
  • Infrastructure failures. When Hermes' failure breaker parks a card only because the host
    failed (gateway, worker persistence), the plugin undoes the park, within a budget of 2 undos per
    card per 24 h. A burst of 3 infrastructure exits within 1 h raises one systemic alert.
  • Visibility. explain says why a card is (not) moving, status lists the fleet, and a pinned
    Telegram message (the live panel) is kept up to date. status --watch shows the same panel in
    the terminal.

The plugin coexists with Hermes' own notifier: it never repeats the native completed, blocked,
gave_up, crashed, review or block_loop_detected messages.

Status: v0.4.0.


πŸ› οΈ Architecture

flowchart TD
    subgraph Workers ["Every worker profile"]
        Guard["Worker guard (pre_tool_call)"] -->|"structured ask on kanban_block"| Board[("Hermes kanban boards")]
    end

    subgraph Coord ["Coordinator profile (gateway)"]
        Tick["on_kanban_dispatch_tick"] --> Coordinator["Coordinator (leader lock)"]
        Exit["on_kanban_worker_exited"] --> Coordinator
        Coordinator --> Store[("Plugin state (SQLite)")]
        Coordinator -->|"comments, unblock, undo, release"| Board
        Inbound["pre_gateway_dispatch"] -->|"owner replies"| Coordinator
    end

    subgraph Desktop ["Hermes Desktop"]
        Page["Empowered page (desktop/plugin.js)"] <--> Backend["Backend (dashboard/plugin_api.py)"]
    end

    Coordinator -->|"reminders, pinned panel"| Telegram["Telegram Bot API"]
    Telegram -.->|"replies"| Inbound
    Backend --> Store
    Backend --> Board
    Backend -->|"running-card summary"| Aux["Hermes auxiliary model"]
  • Runtime: inside the Hermes gateway; no extra process or daemon.
  • Language: Python, standard library only.
  • State: the plugin's own SQLite store and leader lock under plugin-data/kanban-empowered.
  • Kanban access: Hermes' kanban domain functions only; the plugin never writes kanban.db.
  • UI: Hermes Desktop plugin SDK, plus a settings form generated from plugin.yaml.

πŸ“‹ Requirements

  • Hermes Agent at revision bf0203a794 (the revision this version was written and tested
    against; doctor prints both hermes_compat and the installed hermes_head), with the kanban
    enabled.
  • Optional: the core patch patches/0001-kanban-veto-hooks.patch. It adds the
    kanban_pre_claim and kanban_pre_complete veto hooks. The plugin uses only kanban_pre_claim, to hold
    new claims on a Suspended or Done project (see "Project status"); everything else behaves the same
    with or without the patch. Without it, doctor reports veto_hooks: missing and the coordinator
    warns once (log and Telegram).
  • Python standard library only (no extra dependencies).

πŸ”’ Disclosures

What the plugin does beyond its own data, for review before installing:

  • Network. Only the Telegram Bot API at api.telegram.org (sendMessage, editMessageText,
    pinChatMessage; it never polls the bot or calls getUpdates). When that host is unreachable it uses
    Hermes' own IPv4 fallback path (plugins.platforms.telegram.telegram_network), as Hermes' Telegram
    adapter does: IPv4 literals of api.telegram.org with Host/SNI kept, discovered (unless
    TELEGRAM_FALLBACK_IPS is set) with DNS-over-HTTPS lookups of api.telegram.org at dns.google and
    cloudflare-dns.com, and the proxy Hermes resolves (TELEGRAM_PROXY / system proxy). The "Current task"
    line also calls the Hermes auxiliary model (see "Running cards" below), through Hermes' own client and the
    provider you configured. Nothing else; no telemetry or usage reporting.
  • Long-running work. No extra process and no daemon. The coordinator runs inside the gateway's kanban
    dispatch tick (on_kanban_dispatch_tick, evaluating at most every 30 s), in the coordinator profile only,
    behind a leader lock in shared_state_dir; short-lived helper threads bound each Telegram call, DNS lookup and running-card summary.
  • Reads outside its own data. Every live board's kanban database and board metadata, through Hermes'
    kanban functions (read-only except the writes below), plus, for the Indicators tab, one read-only query of
    each board's card events on the connection Hermes opens; the Telegram bot token, through Hermes' secret scope
    (agent.secret_scope.get_secret; see "Configuration"); for doctor only, each profile's config.yaml
    (is the plugin enabled there) and the Hermes checkout's git HEAD files (installed revision). The state
    store lives under the coordinator profile and is read by the plugin in every other profile.
  • Telegram replies. Replies from the configured owners to the plugin's own messages are consumed by the
    plugin before they reach the agent (pre_gateway_dispatch). Everything else passes through untouched. An
    answer to a card a worker cannot run is not consumed but rewritten into an instruction for the Hermes
    session of that same chat ({"action": "rewrite"}).
  • Running cards. To show what a running card is doing, the Desktop backend reads the worker's recent
    session from its profile's state.db, read-only: what the agent wrote, including its reasoning, and the
    tool names; never commands or tool output. It redacts secrets (agent.redact) and sends that to the Hermes
    auxiliary model (agent.auxiliary_client; auxiliary.kanban_empowered in config.yaml, else auto), only
    when the session changed and at most once a minute per card. This consumes tokens from that provider.
    Redaction is pattern-based, so a secret an agent wrote in an unusual form could reach the provider.
  • Writes. On kanban cards, only through Hermes' kanban domain functions, never by writing kanban.db:
    comments, unblocking a card waiting on a person when its owner answers (Telegram, Desktop or the done
    command) unless a worker cannot run it (then it is only commented and handed off), undoing a park caused by an infrastructure failure (within the per-card budget), and reassigning
    a guard-held card when you run release. Its own SQLite store and leader lock under
    plugin-data/kanban-empowered (shared_state_dir). Telegram messages to the configured owner chats only,
    with one pinned live panel in the default owner's chat.
  • No shell commands, no subprocesses, no stored credentials (it never writes or caches the token).
  • Private core imports (all in ke/hermes_api.py, the plugin's only adapter to Hermes; hermes plugins validate lists them as a rule 9 warning): hermes_cli.kanban_db, kanban_db_boards and
    kanban_db_connect (board and card reads and writes), agent.i18n and agent.i18n_layers (the Hermes
    language and the plugin's locale packs), plugins.platforms.telegram.telegram_network and
    agent.ssl_verify (the Telegram fallback path and its trust store), agent.auxiliary_client and
    agent.redact (the running-card summary), tui_gateway.launch_profile_policy
    (the launch profile's secret scope inside the gateway tick), hermes_cli.profiles (profile names and
    homes), hermes_cli.plugins (veto-hook detection), hermes_yaml (reading config.yaml for doctor) and
    hermes_cli itself (locating the checkout for doctor). A seam request for these will be filed upstream.
  • Optional core patch. patches/0001-kanban-veto-hooks.patch is never applied by
    the plugin; applying it is a manual step. The plugin registers kanban_pre_claim only when the running
    Hermes exposes that hook, so on a stock build it is not registered, and on a patched build hermes plugins validate reports it as an undeclared hook, by design (it is not in provides_hooks because a stock build
    does not know it).

πŸš€ Install

Step-by-step guide with verification and rollback: docs/INSTALL.md. Live acceptance results of the first release (v0.1): docs/ACCEPTANCE-v0.1.md.

Plugins, their state and their settings are per Hermes profile. Install and enable the plugin in
every profile that runs kanban workers (builder, devops, reviewer, ...) and in the profile of
the gateway that acts as the coordinator (by default default).

For each profile:

  1. Put this repository in the profile's plugin directory, <profile home>/plugins/kanban-empowered/
    (~/.hermes/plugins/kanban-empowered/ for default,
    ~/.hermes/profiles/<name>/plugins/kanban-empowered/ for a named profile).
    hermes plugins install <git url> does the same.
  2. Enable it: hermes plugins enable kanban-empowered (it goes into plugins.enabled).
  3. Add the settings below to that profile's config.yaml. Every profile must agree on
    coordinator_profile and shared_state_dir (the default shared_state_dir is derived from
    coordinator_profile, so leaving both at their defaults everywhere is consistent).
  4. Run hermes kanban-empowered doctor in that profile.

What runs where:

  • Every profile registers the worker guard (pre_tool_call): a kanban_block that waits on a
    person must carry a structured ask (Need: / Why: / How to reply:, or the pt-BR labels
    Preciso: / Por quΓͺ: / Como responder:), otherwise the agent is asked to redo the block.
    Optional lines: Subject: / Assunto:, Next step: / PrΓ³ximo passo: and Options: /
    OpΓ§Γ΅es: followed by one A β€” choice line per option.
    Worker profiles open no plugin state.
  • The coordinator profile (only) opens the shared state, evaluates the boards on Hermes'
    dispatch tick (at most every 30 s), sends Telegram messages, reads the Telegram replies and
    records worker exits. A leader lock in shared_state_dir makes sure only one coordinator
    process acts at a time; a second one stays passive.

βš™οΈ Configuration

Settings live under plugins.entries.kanban-empowered.settings:

plugins:
  entries:
    kanban-empowered:
      settings:
        mode: enforce                 # enforce | cooperative-only
        # language: pt                # plugin messages' language; default: follow Hermes
        coordinator_profile: default  # the profile whose gateway is the coordinator
        # shared_state_dir: C:/Users/me/AppData/Local/hermes/plugin-data/kanban-empowered
        telegram:
          owner_ids: { owner: 123456789, ops: 5550001 }
          pin_live_panel: true
          reply_ttl: 7d
        waits:
          default_owner: owner
          reminders: [30m, 2h]
          escalate_after: 8h
          escalate_to: ops
          digest: daily
          human_kinds: [needs_input, capability]
          require_structured_ask: true
          # outside_worker_profiles: [ops-desk]   # cards of these profiles never go back to a worker
          handoff_alert: 15m
          handoff_repeat: 1h
        boards:
          side-project:
            waits: { default_owner: ops }
        guards:
          alert_after: 30m
        infra_failures:
          undo_budget: { count: 2, window: 24h }
          alert_count: 3
          alert_window: 1h
          # patterns: ["Kanban execution unknown", "retained by owner",
          #            "Gateway connection failed", "WorkerPersistenceError"]
KeyDefaultMeaning
modeenforceenforce or cooperative-only. Validated, but without effect for now (reserved for the veto hooks).
languagenoneLanguage of the plugin's messages (pt, en, ...). None follows the Hermes language.
coordinator_profiledefaultThe profile whose process acts as the coordinator.
shared_state_dirthe coordinator profile's plugin-data/kanban-empoweredThe plugin's SQLite state and leader lock, shared by all profiles. Default: <hermes root>/plugin-data/kanban-empowered when coordinator_profile is default, else <hermes root>/profiles/<coordinator_profile>/plugin-data/kanban-empowered. Must be on a local NTFS (or other local) disk: the leader lock relies on hard links and atomic renames, which network shares and some sync folders do not provide.
telegram.owner_ids{}Owner name to Telegram id. Each value is BOTH the person's Telegram user id and the id of their private chat with the bot (in a Telegram DM they are the same number): messages go to that chat, and a reply is accepted only from that user.
telegram.pin_live_paneltrueKeep a pinned live panel in the default owner's chat.
telegram.reply_ttl7dHow long a reminder can still be answered.
waits.default_ownerownerOwner of the waits on any board without an override. A config from before 0.4 that names its owner sponsor in telegram.owner_ids (and sets no default owner) keeps sponsor.
boards.<board>.waits.default_ownerPer-board owner.
waits.reminders[30m, 2h]Reminder times, counted from the start of the block.
waits.escalate_after8hWhen the escalation goes out (to the owner, plus a copy to escalate_to).
waits.escalate_tononeOwner name that receives a read-only copy of escalations. It cannot resolve them.
waits.digestdailyRepeat interval after the escalation (hourly, daily, weekly or a duration).
waits.blocking_digest_everysame as waits.digestDigest interval for waits that hold other cards back (hourly, daily, weekly or a duration like 6h). Empty = the same as waits.digest.
waits.human_kinds[needs_input, capability]Block kinds that wait on a person (an untyped block counts too).
waits.outside_worker_profiles[]Profiles whose cards are never unblocked for a worker: an answer hands them off to an interactive session.
waits.handoff_alert15mA handoff nobody picked up alerts the owner after this long.
waits.handoff_repeat1h...and again every this long while still not picked up.
waits.require_structured_asktrueThe worker guard requires the three-line ask.
guards.alert_after30mHow long a respawn guard may hold a card before the owner is told (repeated every waits.digest).
infra_failures.undo_budget{count: 2, window: 24h}Breaker parks undone per card per window.
infra_failures.alert_count / alert_window3 / 1hSystemic alert threshold.
infra_failures.patternssee aboveError substrings that mark a worker failure as the host's.

Durations accept s, m, h, d (30m, 2h, 7d) or plain seconds.

The Telegram bot token is TELEGRAM_BOT_TOKEN of the coordinator profile (the same bot the gateway
already uses), read only through Hermes' secret scope (agent.secret_scope.get_secret), never from a bare
os.environ read or a file. On a multi-profile (multiplexed) gateway the dispatch tick has no profile bound;
there the plugin takes the launch profile's own value from Hermes' launch-profile scope, and in a context
serving another profile it gets no token (one warning) rather than borrowing one. The plugin only calls
sendMessage, editMessageText and pinChatMessage; it never polls the bot.


πŸŽ›οΈ Settings screen

In Hermes Desktop the plugin has a settings form (Capabilities, plugin gear, or Settings > Plugins),
generated from the config_schema in plugin.yaml. It edits the common keys:

Form fieldSame as in config.yaml
Message languagelanguage
Modemode
Owner Telegram idtelegram.owner_ids.<default owner>
Default ownerwaits.default_owner
Reminders (30m,2h)waits.reminders
Escalate afterwaits.escalate_after
Digest everywaits.digest
Digest every (waits that block cards)waits.blocking_digest_every
Escalate towaits.escalate_to
Require structured askwaits.require_structured_ask
Pin live paneltelegram.pin_live_panel
Stuck-card alert afterguards.alert_after
Infra undo budget / windowinfra_failures.undo_budget.count / .window
Show the sidebar menushow_sidebar_menu (Desktop dashboard, see below)
Show the Kanban buttonshow_kanban_button (Desktop dashboard, see below)

The form stores each value as a flat key (plugins.entries.kanban-empowered.settings.default_owner,
not ...settings.waits.default_owner), because that is how Hermes Desktop reads and writes plugin
settings. The plugin folds those flat keys onto the nested ones, with this precedence:

  1. A non-blank flat key (what the form wrote) wins over the nested key it stands for.
  2. A blank flat value ("") counts as unset and falls through to the nested key, then the default.
  3. telegram_owner_id becomes owner_ids: {<default owner>: <id>} only when telegram.owner_ids
    is not set; an explicit owner_ids mapping always wins.

Hand-written nested config keeps working unchanged. When a form value differs from a nested
config.yaml value it shadows, the plugin logs one warning per load and hermes kanban-empowered doctor
prints a config_conflict: row for each; a telegram_owner_id that an explicit owner_ids leaves
unused (no id there for the default owner, or a different id) is reported the same way.

Limits of the form:

  • It shows the schema default for a field until that field is saved, not the value that is effective
    from config.yaml. Until the form writes the field, the nested value (or the built-in default) applies.
  • Booleans and numbers cannot be unset from the form: once saved, Require structured ask, Pin live panel and Infra undo budget always hold a value. To go back to the nested or default value, delete
    the flat key from config.yaml.
  • Owner Telegram id cannot be cleared from the form (an empty number is rejected). Remove
    telegram_owner_id from config.yaml to drop it.
  • A blank Reminders field means the waits.reminders value from config.yaml, or the default 30m,2h when
    there is none. "No reminders" cannot be set from the form.
  • Escalate to only names a contact; that contact needs a chat id in telegram.owner_ids, which can
    only be edited in config.yaml (the form has no mapping field). Without it, escalation copies are not sent
    and the coordinator warns once.

Keys the form cannot express stay in config.yaml: coordinator_profile,
shared_state_dir, telegram.owner_ids (several owners), telegram.reply_ttl, boards,
waits.human_kinds and infra_failures.alert_count / alert_window / patterns.

docs/catalog/kanban-empowered.yaml is the draft entry for the
Hermes plugin catalog (the card image comes from there, not from plugin.yaml).


πŸ–₯️ Desktop dashboard (Empowered)

The package also ships a Hermes Desktop half (desktop/plugin.js) and its backend
(dashboard/plugin_api.py, mounted by Hermes at /api/plugins/kanban-empowered/). Two switches,
both off until you turn them on, as for every Desktop plugin: the agent plugin enabled in the
profile (plugins.enabled, which also mounts the backend; restart the gateway after enabling) and
the Desktop half enabled in Capabilities > Plugins.

  • Kanban-Empowered in the sidebar (setting Show the sidebar menu) opens the page; a compact
    Empowered button appears in the header of the Kanban page (setting Show the Kanban button;
    needs the bundled Kanban Desktop plugin enabled and a Desktop that exports the page-header area).
    The palette command Kanban Empowered opens it too.

  • The page shows four counters (need you, impacted cards, active workers, incidents), then the
    Project map, then two columns. On the left, Needs you (sorted by cards held behind, then age;
    infrastructure cards whose undo budget is used up in red). On the right, Running now, Coordinator
    at work
    (the last 10 actions: unblocks via Telegram/desktop/CLI, released guards, undone infrastructure
    failures, reminders sent, panel updates) and Infrastructure (failures in the last hour, systemic
    alert, Telegram path, cards out of retries). It refreshes every 10 s and can be filtered by board.

  • Needs you and Running now group their cards in one box per project, in the order of the most
    urgent card; each box folds, and the folded ones are remembered. The text of a card is selectable; a
    command or a reply to type (code in backticks with a space, or a fenced block) gets its own Copy
    button, while a short name in backticks (a card, a branch) stays in the sentence.

  • Explain this project's blocks, on each project box of Needs you, asks the Hermes auxiliary model
    (the same one that writes the "Current task" lines) for one plain account of every card of that project
    that waits on you: what each one is stuck on, what exactly to answer or run, and in which order, the card
    that frees the most first. Only the needs-you entries go to the model (their request, why, options and
    counts, already redacted); the cards are given as data, never as instructions. The call runs in the
    background (GET /story?board=<slug> is polled every 3 s while it writes, with a progress indicator),
    the story is kept until the waiting cards change, and a failed call is retried at most once a minute.
    Check it against each card before answering.

  • View details opens a drawer with the project, the request exactly as the Telegram reminder
    words it, the options, the explain conditions and the last comments. Send answers it the same
    way a Telegram reply would (an option letter or a confirmation word resolves; a "not yet" only adds
    a comment; any other text is the answer and is posted on the card) and the card comment says
    "via Kanban-Empowered (desktop)". The answer is applied only while the card is still blocked on the
    block you were looking at.
    Only a card waiting on a person can be answered (as on Telegram); a card parked by Hermes'
    failure breaker is shown read-only.

  • Any authenticated Hermes Desktop or web-dashboard session against this gateway can answer the
    waits of any board (Telegram checks the owner of each board; the dashboard does not), and the answer
    is recorded as "desktop" without a user name.

  • The page has two tabs. Main is everything above. Indicators shows where the flow gets stuck,
    for the last 7 or 30 days, on every active board or the one picked in the board filter:

    • Audit: a few sentences, chosen by fixed rules (no model), naming the biggest bottleneck, the
      busiest and the least stable profile, your average response time and how many open cards are old;
    • Where the time goes: time cards spent in queue, running, waiting on you, waiting on another card,
      held by a guard or parked by failures, per project;
    • Queue per profile: cards waiting for each agent and for how long on average;
    • Waiting on you: average response, reminders per wait, open waits and the response per day;
    • Rework and failures: failed and repeated runs per profile (infrastructure or sign-in, content,
      quota, returned review or block loop);
    • Age of open work: open cards by age.

    It is computed from the events Hermes already records on each card plus the plugin's sent reminders, and
    cached for one minute.

  • Project map (between the counters and the two columns of Main; folded until a project is picked,
    and the fold button hides it again): pick a project and its cards are drawn as a flow,
    one lane per agent, with their links. By profile places each card by dependency level; Timeline
    places done cards by the period they were completed in (hour, day or week, from how spread out they are),
    then Now (running, in review, blocked) and Up next. Drag to move, Ctrl + wheel or the corner
    buttons to zoom (the wheel alone keeps scrolling the page), Fit to see it all.

    • At most 100 cards: every open card first, then the latest done ones. A link to a card left out shows
      as "+N before" / "+N after" on the card, and "Showing 100 of N cards" says when cards were left out.
    • A card waiting on you is amber and opens the same drawer as Needs you; any other card opens a small
      read-only panel with its dates, first sentence, and the cards it depends on and releases.
    • A dashed box after the last column says the end is only known so far: agents create cards as the
      project moves on.
    • The map only reads (GET /graph, GET /card), refreshes every 10 s while it is on screen, keeps your
      position and zoom, fetches nothing until a project is picked, and is cached for 5 s per project.

Texts follow the plugin language (language, else Hermes'); the product name is not translated.

Project status (Active / Suspended / Done)

Hermes boards have no lifecycle status, so the plugin keeps one per board in its own state
(state.db; board.json is never touched). A board without a status is Active. Set it from
the Projects button of the dashboard or with hermes kanban-empowered board-status.

A Suspended or Done board:

  • leaves Needs you and the four counters; its items go to the collapsed Suspended projects (N)
    section, tagged with the status, and can still be opened and answered. A reply to an older Telegram
    reminder of a now-suspended board still resolves it too (same version checks as any reply);
  • gets no Telegram reminders, escalations or digests for its waits, and the pinned panel leaves it out
    (one line "N suspended projects" at the end). Infrastructure alerts are unaffected;
  • has its new claims held through the core veto hook kanban_pre_claim (the card stays ready, with a
    claim_refused event "Project suspended in Kanban Empowered β€” reactivate it to continue."); workers
    already running finish normally. Without the veto hooks patch (doctor: veto_hooks: missing) claims
    are not held; the rest still applies. Review-lane claims are not held yet: the dispatcher picks up a
    card in review through claim_review_task, which the current core patch does not hook, so a reviewer
    can still start on such a board; this needs a core patch update (doctor row boards_hold_scope).

hermes kanban-empowered explain <card> shows "start held: project suspended" for a ready card of such a
board. While the only ready cards are on suspended/done boards, the gateway may log its "kanban dispatcher
stuck" warning every few minutes (nothing was spawned although cards are ready); it is expected and harmless.

Back to Active, claims flow again and the open waits restart their reminder ladder from that moment
(first reminder one first stage later, no burst of the stages missed meanwhile).


πŸ’» Commands

CommandWhat it does
hermes kanban-empowered doctorCompatibility and setup diagnostics (see below).
hermes kanban-empowered explain <card> [--board B]Why a card is (not) moving: dependencies, guard, live run, freshness, human wait.
hermes kanban-empowered status [--watch]Running cards, human waits, guarded cards, resolved today. --watch redraws the live panel every 5 s until Ctrl+C.
hermes kanban-empowered done <card> [--board B]Resolve a card's open human wait, exactly like a done reply on Telegram (same version checks).
hermes kanban-empowered release <card> --to <profile> [--board B]Hand a card held by a respawn guard (active_pr, blocker_auth) to another profile.
hermes kanban-empowered board-status [<board> [active|suspended|done]]Without arguments, every board with its project status; with a board, its status; with a status (also ativo, suspenso, concluΓ­do, accents optional), set it.

Telegram replies

Reply (with Telegram's "reply" function) to a reminder or to the pinned panel and name the item:
1 β€” conectei, 2 β€” o campo ficou pequeno, 3 β€” A (also 1 – …, 1 - …, 1: …, 1) …,
1. …, 1 …). A reminder with a single item also takes the bare text; the pinned panel only takes
numbered replies (anything else is a normal message for the agent). The text after the number:

  • a letter the item lists as an option (3 β€” A) picks that option and unblocks the card (the choice
    is commented); a letter it does not list, or a bare ok on an item with options, changes nothing
    and the plugin asks for a listed letter;
  • a confirmation word unblocks the card: the item's own reply words (from its How to reply:) or
    feito, conectei, validado, liguei, ok, aprovado, pronto, done, connected,
    validated, approved (any case, trailing punctuation/emoji allowed);
  • an explicit "not done" (nΓ£o, ainda nΓ£o, negativo, not yet, not, nope, never, and no:
    at the start in English, only on its own in Portuguese) only adds a comment; the card keeps waiting;
  • any other text is your answer: the card is unblocked and the text is posted as a comment, so the
    agent continues with it;
  • several items and no number: the plugin asks which item.

A reply is acted on only when it comes from the configured owner of that item, in the owner's own
chat, to a message the plugin sent, before reply_ttl, and while the card is still blocked on the
same block it was reminded about. If the card was blocked again (a new block, including a park by
Hermes' failure breaker), the reply changes nothing and the plugin says so. Replies from anybody
else are ignored and continue to the normal gateway flow. Every resolution becomes a card comment
with its author.

Requests addressed to another agent

Hermes has no block kind for "this waits on another agent": a worker that needs a code change from another profile
blocks with needs_input like any request for a person, and when the same kind repeats after an unblock, Hermes moves
the card to triage (block_loop_detected) "for a human". The plugin reads who the request is for: when the ask's
Need (or the reason's first line) opens by addressing a name (Diretor, …, @diretor: …) that is one of this
installation's Hermes profiles (the folders under <hermes root>/profiles, plus default), the block is not a
human wait. It sends no reminder, is not in Needs you or the badge, and Explain names the agent the request is
for. The plugin's own role names (the keys of telegram.owner_ids and waits.escalate_to) always mean you: a request addressed to one of them stays
yours even when a profile has that name. Only an opening address counts; a name later in the sentence does not.

Hermes does not deliver such a request to the agent named in it: the card stays blocked (or in triage) until that
agent, or you, act on it.

Cards that wait on another card

Hermes records a card created blocked (initial_status) the same way whether it waits on a person or on another
card that a person must run first; it has no link for "this card unblocks that one" other than a parent, which
would keep the card in todo instead. So the plugin reads one signal every installation has: the card id
(t_ and 8 hex digits) in the body or the comments of another card that is itself waiting on a person, on
the same board
. The plugin's own comments are not read.

A waiting card cited that way is covered: it appears under the citing card in Needs you ("Unblocks along",
with its cards held counted there), the Telegram panel and the badge leave it out, and it sends no reminder of
its own. Its drawer and Explain name the card to answer first; it can still be answered directly. Two cards
citing each other cover neither, a chain resolves to the card nobody covers, and a cycle covers nobody. When the
citing card is resolved, a covered card still blocked stands on its own again, with the reminder its age calls for.

A card created already blocked carries no reason for a person (Hermes records only initial_status). Its item
does not pass the card title off as a task for you: it says who created it blocked, that a reply unblocks it and
sends it to a worker of its assignee, and to ask the creator when it is unclear what is missing; the title is
shown as Card: …. A later block with no reason keeps the usual item. Agents usually explain such a wait in a
comment right after creating the card: the first comment its creator wrote since the block (a leading bold label
and markdown emphasis dropped) is then the request, on the Desktop and on Telegram, like any block reason.

Handoffs to an interactive session

Hermes sends every unblocked card with an assignee to a worker of that profile. Some cards cannot be run
by a worker: they need the person's own session, a credential only that profile has, or a command the
worker is fenced from. Unblocking them only produces another worker that blocks them again.

An answer that would unblock a card (a confirmation, an option, free text) is handed off instead when:

  1. you marked the card Run outside a worker in the Desktop drawer;
  2. its assignee is in waits.outside_worker_profiles (empty by default);
  3. its current block has Hermes' capability kind: a worker saying it cannot do this;
  4. one of its blocks was already handed off: a card is never sent back and forth between a worker and you.

Nothing here depends on profile names, languages or conventions of one installation: only the block kinds and
events every Hermes records, plus the two options above. The first block of a card cannot be told apart
beforehand and may still be unblocked; the worker's capability block is what turns it.

A handoff never changes the card: it stays blocked (manual and safety blocks are kept), and the live block
version is checked first, so an answer to an old block does nothing. The plugin records who answered, when,
why and for whom, comments the card, and:

  • Telegram: your reply goes on to the Hermes session of that chat as an instruction ("run card … here,
    then complete it"), and the plugin tells you the card was not unblocked;
  • Desktop: the drawer shows that instruction with a Copy button, to send in a Hermes chat session.

The card leaves Needs you for With an interactive session, which shows how long it has waited there.
It counts as picked up at the first sign of a session on the card (a comment by anybody but the plugin,
the card completed, unblocked or blocked again). If nobody picks it up within waits.handoff_alert (15 min),
the owner gets a Telegram alert, again every waits.handoff_repeat (1 h). Reminders for that block stop.
Unblock for a worker anyway (Desktop) or done --worker (command line) still unblocks it, and clears the
card's handoff memory.

doctor output

KeyValue
hermes_compatHermes revision this plugin version targets.
hermes_headInstalled Hermes revision (unknown if it cannot be read).
veto_hookspresent / missing (the core patch; the plugin uses kanban_pre_claim to hold claims on suspended/done projects).
coordinatorPID of the process holding the leader lock, or none.
active_profileProfile of the process running doctor.
coordinator_profileConfigured coordinator profile.
shared_state_dirResolved state directory.
profiles_with_pluginProfiles where the plugin directory exists and config.yaml enables it (plugins.enabled, not in plugins.disabled) or has a plugins.entries.kanban-empowered section.
telegram_tokenpresent / missing: whether Hermes' secret scope resolves TELEGRAM_BOT_TOKEN in this process (the token itself is never printed).
owner_chatsNumber of entries in telegram.owner_ids.
boards_suspendedBoards whose project status is Suspended or Done (slug, slug (Done)), or none. Read-only.
boards_hold_scopeWhat a Suspended/Done board holds: new claims, except review-lane claims (not hooked by the current core patch; needs a core patch update), or nothing when the veto hooks are missing.
telegram_pathOnly once a Telegram client has recorded one: how the Bot API was reached last, <host> (hostname) or <ip> (IPv4 fallback).
config_conflictOne row per settings-form value that shadows a different config.yaml value, or a telegram_owner_id that telegram.owner_ids leaves unused.
configOnly when the settings are invalid: the error. The plugin then runs the worker guard on defaults and does not start the coordinator.

Human-facing text follows the Hermes language (English by default; pt and pt-br included).
The optional top-level setting language (e.g. language: pt) overrides it for this plugin's
messages only. Telegram messages never show card ids, hashes or role names; the CLI keeps the ids.


🚧 What it does not do yet

  • The veto hooks are used only to hold claims on Suspended/Done projects. There is no refusal at
    completion time, no resource locks or quota groups (quota, held commands), no gate verdicts
    or four-eyes review.
  • Review-lane claims on a Suspended/Done project are not held yet (needs a core patch update, see
    "Project status").
  • No agent tools (kanban_true_state, kanban_verdict); the only agent-facing check is the
    structured ask on kanban_block.
  • Breaker parks are not tracked as human waits (no reminders for them): the infrastructure
    recovery and its alerts handle them, and Hermes' own notifier announces the gave_up.
  • No quiet hours. Reminders follow the wall clock; while the gateway is down they wait, then go
    out condensed into one message per owner.
  • Telegram is the only messaging channel; the Desktop dashboard is the other way to answer.
  • The Desktop dashboard does not check per-board owners (see "Desktop dashboard").

πŸ“„ License

This project is open-source under the MIT License. See LICENSE for details.

README from the reviewed commit b16d3f9; it updates when the author re-pins.

Developer Mode

Explore built-in Hermes toolsets and actions.

HermesAgent

Developer?

Create a Hermes extension for Desktop or agent workflows.

Developer Section