nelsonpires5/herdr-board/skill

herdr-board

This is the operational skill for people and dispatched agents using herdr-board. It covers the TUI, CLI, cards, runs, comments, columns, and Herdr-backed spaces; it does not prescribe how to develop, prototype, test, or release herdr-board itself.

A card is a title/description plus harness/model/effort, optional harness permission, and a target Herdr session and workspace. New cards default to Pi; the built-in catalog is pi, claude, codex, opencode, antigravity (in that order), then any config-defined [harness.NAME]. Columns are pipeline stages: manual waits for a person and auto dispatches a visible agent run on entry. Each canonical Git root (or exact non-Git CWD) is a project holding named boards (every project's first board is main); the preserved Global project remains available. Agents report through board; never edit the database. The daemon owns state and column transitions.

Inside a run

$BOARD_CARD_ID, $BOARD_RUN_ID, and $BOARD_SOCKET are preset. board comment posts as agent:$BOARD_RUN_ID when the run id is present. Do the stage's work, comment the result, then close the run.

Rules — follow exactly:

• Always comment before `board done`. The next stage receives the comments; a bare done loses

your useful result.

• board done --outcome ok means the stage goal was met. --outcome fail means it was not met;

fail is a semantic verdict, not merely a report of a recovered tool error.

• Never move, cancel, or retry your own card to advance it. board done applies the column's

transition. Use cancel/retry only when the operator or task explicitly requires it.

• A card id is optional for top-level comment and done; both default to $BOARD_CARD_ID.

board comment "Implemented X; added tests, all green. Touched src/foo.rs."
board done --outcome ok --summary "feature X shipped, tests green"
# If the stage goal was not met:
board done --outcome fail --summary "2 integration tests still fail; needs schema work"

TUI

Run board tui or invoke the open-board Herdr plugin action. Use arrows or h/j/k/l to navigate, n for a card, N for a column, m to move a card (form fields: Project → Board → Column → Position; the move never changes the selection), M to reorder the focused column, O to reorder the selected card within its column (j/k stage, Enter commits, Esc cancels), Enter for detail, e/E to edit a card/column, a to archive/restore, v for active/all/archived visibility, p to switch project, b to switch board, and ? for help. Moving into an auto column dispatches a run. o focuses the newest same-session run pane; Enter on an awaiting card confirms it through the same completion channel as board done --outcome ok. Below 60 columns the TUI switches to a single-column Compact layout with a tappable ‹ [ ⇄ <column> n/N] › header; the project and board selectors appear as separate Project: / Board: header rows at every breakpoint (b opens the board picker directly; ⇄ Other projects… drills to the project picker).

CLI taxonomy

The nested forms are canonical. --board (a stable id or canonical scope path), --project (a canonical scope path), and --json are all global flags: either position parses identically, before or after the subcommand path.

board --board <ID|PATH> card list --json
board card list --board <ID|PATH> --json     # identical
board --project /path/to/repo board list

Without --board/--project, board-aware commands use the selected project (and its selected board); BOARD_SCOPE_PATH is a deterministic automation override that bootstraps the selection at startup when none exists yet. card create/list, column list, and board commands use the selected project/board. Card-id operations infer the card's own board.

Projects and boards

board project list [--json]
board project show [PATH] [--json]
board project create PATH [--json]
board project select PATH [--board ID|NAME] [--json]
board board list [--all|--project PATH] [--json]
board board show [ID|PATH|NAME] [--json]
board board open <PATH> [--json]
board board create NAME [--project PATH] [--json]
board board select ID|NAME [--project PATH] [--json]
board board rename [SELECTOR] NAME [--json]
board template apply pipeline [--json]

A project is a canonical scope path (Git root or existing directory). project create requires the directory to already exist and never creates one; it auto-selects the project and its first board main. project select optionally picks one of the project's boards by id or name. board list defaults to the selected project's boards (--all lists every project's, --project PATH picks another project); board create names a board in a project (case-insensitively unique there) and auto-selects it; board select persists a board — and its project — as the context; board open keeps its open-or-create semantics and BoardSnapshot output but resolves the project's selected-or-main board without changing the selection. board show and board open return a snapshot with board, columns, cards, and active_runs. The pipeline template is atomic and only applies to an empty board containing exactly the seed Todo column; it returns the resulting column array.

Cards

board card create --title TITLE [-d DESCRIPTION] [--column COLUMN] \
  [--harness HARNESS] [--model MODEL] [--effort EFFORT] [--permission MODE] \
  [--session SESSION] [--space-kind workspace|new-workspace] \
  [--space-ref REF] [--space-cwd DIR] [--json]
board card edit ID [--title TITLE] [-d DESCRIPTION] [--clear-description] \
  [--harness HARNESS] [--model MODEL|--clear-model] [--effort EFFORT|--clear-effort] \
  [--permission MODE|--clear-permission] [--session SESSION|--clear-session] \
  [--space-ref REF|--clear-space-ref] [--space-cwd DIR|--clear-space-cwd] [--json]
board card show ID [--json]
board card list [--column COLUMN] [--visibility active|all|archived] [--json]
board card move ID COLUMN [--position ZERO_BASED_POSITION] [--destination-board ID|PATH] [--to-project PATH --to-board NAME|ID] [--json]
board card duplicate ID [--json]
board card archive ID [--json]
board card restore ID [--json]
board card delete ID [--yes] [--json]

card duplicate copies a card into a fresh idle card inserted directly below it: title gains (copy), and description, harness, model, effort, permission mode, session, and space configuration are copied verbatim — but status is idle with no runs, comments, conversation id, or archive flag. The original is never modified, and the copy is never dispatched, even in an auto column; run it (or move it) explicitly like any idle card. In the TUI, C duplicates the focused card from the board or card detail.

card new is retained as an alias for card create. A new card defaults to Pi; an omitted model or effort uses the harness default. --harness codex selects the built-in Codex adapter: models are free-form (--model any string), every effort level is accepted (off|minimal|low|medium|high|xhigh|max; off is delivered to codex as model_reasoning_effort=none), and --permission takes ask-for-approval|approve-for-me|full-access. These are board-facing presets: ask on request in a workspace-write sandbox, automatic review in a workspace-write sandbox, or bypass approvals and sandbox respectively. Codex mints its own conversation thread id — the board never invents one — and captures the integration-reported id after launch, so later stages can resume/fork the same conversation; a minted run whose id was never reported cannot be reopened by id (card run focus refuses; use card run retry for a new run). --harness antigravity selects the built-in Antigravity CLI adapter (Herdr kind/executable agy): models come from the live agy --output-format json models catalog (free-form when the catalog is unavailable), efforts are low|medium|high per model (a fixed-effort model offers none), --permission takes sandbox|always-proceed (no permission set keeps your own configured default), and resume/retry re-attach to the SAME conversation with --conversation <id> — antigravity has no fork. The id is self-minted by the CLI and captured from the Herdr integration after launch, so it must be installed (herdr integration install antigravity-cli) for reuse/rescue to work. new-workspace requires both --space-ref and --space-cwd. For an existing workspace, set --space-cwd when its live panes intentionally use different directories; without it, dispatch requires all non-empty live pane cwd values to agree and fails closed when they differ. Creating directly in an auto column dispatches immediately. card list defaults to active cards; all includes archived cards and archived returns only archived cards. card show includes current comments and run history; soft-deleted comments are omitted.

A cross-board move goes on --destination-board (an id or path); a cross-project move uses --to-project PATH --to-board NAME|ID, and neither ever changes the persistent selection or recency. The old fallback — a global --board naming a different board than the card's — still works but prints a deprecation warning to stderr; do not write new automation against it.

Omitted edit options are unchanged. Explicit --clear-* flags clear nullable values; --clear-description sets the description to an empty string. Harness is required and cannot be cleared (--clear-harness parses but is refused). Model/effort/permission/session/space edits are refused while a card has an open run. Archiving and deletion also require an idle/terminal card; cancel an open run first. Delete is permanent and removes card history. It prompts on a TTY and requires --yes in non-interactive use.

Comments

board card comment add CARD_ID BODY [--json]
board card comment show COMMENT_ID [--json]
board card comment edit COMMENT_ID BODY [--json]
board card comment delete COMMENT_ID [--yes] [--json]
board card comment history COMMENT_ID [--json]

Add returns the compact current comment (id, card_id, author, body, created_at); show/edit return the current record with those fields plus deleted_at; card show prints each comment in that same one-line shape. Delete is a soft delete and returns {"deleted":true}. History returns immutable snapshots from creation through the latest edit; deletion marks the final snapshot. Card detail and run prompts show only non-deleted comments.

When $BOARD_RUN_ID is set, add creates author=agent:<run-id>, and that open durable run may edit or delete only comments owned by its exact agent:<run-id> author. Calls without a run id are human operations and may edit/delete non-system comments. System comments are immutable; deleted comments are immutable. The legacy board comment [CARD_ID] BODY form remains available and defaults the card id to $BOARD_CARD_ID.

Runs

board card run done [CARD_ID] --outcome ok|fail [--summary SUMMARY] [--json]
board card run confirm [CARD_ID] [--summary SUMMARY] [--json]
board card run cancel CARD_ID [--json]
board card run retry CARD_ID [--json]
board card run focus CARD_ID RUN_ID [--origin-socket SOCKET] [--json]

card run confirm is the done --outcome ok channel for an awaiting card. card run focus takes an explicit RUN_ID (there is no implicit "latest run"; read it from card show --json runs[]), returns {action, recorded_pane_id?, run_id, card_id, column_id, harness, session, session_id, pane_id}, and requires that run's pane to belong to the current Herdr session; session is the herdr session name while session_id is the harness conversation id. Without --origin-socket it uses HERDR_SOCKET_PATH or HERDR_SOCK.