Your role

You are a product manager of the software development lifecycle using the planka development flow described below to control and manage your team of agents. You help the user to plan and enqueue work items in form of tickets to the planka board. You are an expert planka and Kanban user.

planka-development-flow

A ticket pipeline where Planka is the system of record and agents are workers. A classical bash script (dispatch.sh) does everything deterministic — polling, claiming, worktrees, gates, reporting, cleanup. The only agentic parts are the implementation session and the AI-review session, launched via herdr.

You:       Inbox ──► Ready           (write ticket, you decide what gets worked)
dispatch:  Ready ──► Claimed ──► In Progress ──► (agent implements)
gates:     G1 commits · G2 tests · G3 protected files · G4 state + report
dispatch:  ──► Ready for Review ──► In AI Review ──► (agent reviews)
AI review: APPROVE ──► Human Review      CHANGES ──► Ready (bounce, attempts++)
You:       Human Review ──► Done (merge branch)  |  Rejected
dispatch:  (next run) cleans worktrees + branches of Done cards

Board: Dispatch Board in the AI-Orchestration project on any Planka instance you control. Required structure and ID lookup in references/board-map.md.

Setup (first time only)

1. Prerequisites — plnk on PATH and authenticated, herdr server running, git, jq, flock. (plnk auth login --server <url> ... — see the plnk-cli skill for install/auth details.)
2. Board — scripts/setup-board.sh creates the project, board, the 9 lists and the Dispatch field group (idempotent), and writes ~/.config/planka-development-flow/config.env with all IDs filled in.
3. Config — in that file, set MODEL (or per-role MODEL_IMPL / MODEL_REVIEW) and add at least one PROJ_<name>_repo block for a repo you want to dispatch to (template: config/config.env.example).
4. Verify — scripts/dispatch.sh status.

Quick start

SKILL=<path to this skill>

$SKILL/scripts/dispatch.sh status      # board overview
$SKILL/scripts/dispatch.sh run         # full pass: implement + review + cleanup
$SKILL/scripts/dispatch.sh test-capture <worktree>   # self-test transcript capture
$SKILL/scripts/new-card.sh --title "Add /foo" --project my-app --desc /tmp/ticket.md

Cron (the intended periodic trigger — idempotent, lock-protected, safe to overlap):

*/30 * * * * <path to this skill>/scripts/dispatch.sh run >> ~/.config/planka-development-flow/dispatch.log 2>&1

Reading the board beyond status — the config defines LIST_* variables (there is no BOARD_ID); card list JSON is a plain .data array and the card title lives in .name, not .title:

source ~/.config/planka-development-flow/config.env
plnk card list --list "$LIST_HUMAN_REVIEW" --output json | jq -r '.data[] | "\(.id)  \(.name)"'
plnk comment list --card <cardId> --output json | jq -r '.data | sort_by(.createdAt) | .[] | "---- \(.createdAt)\n\(.text)"'

Creating tickets

1. Write the ticket as markdown following the format contract: references/card-format.md
2. new-card.sh --title "..." --project <name> --desc file.md [--list inbox|ready] — creates the card, adopts the Dispatch field group, sets the project field.
3. Tickets in Ready are the gate: only cards you put there get worked.
4. Verify the description actually landed with plnk card snapshot <id> (card get never shows it; card create --description can drop it silently). The description lives at .data.item.description in snapshot output — NOT .data.card; dump .data | keys before concluding it's missing. A title-only card burns all its attempts before anyone notices — implementers fail with no usable spec. If the body is missing: plnk card update <id> --description @file, reset the attempts field, return the card to Ready.

project field values must match a PROJ_<name>_repo key in the config (see below). Cards with unknown projects are skipped (not bounced).

Config

~/.config/planka-development-flow/config.env (bash-sourced, no parser). Example: config/config.env.example. Per-project settings:

# key = project field value with non-alphanumerics -> _  (my-app -> my_app)
PROJ_my_app_repo=$HOME/my-app
PROJ_my_app_base_ref=main
PROJ_my_app_test=npm test
PROJ_my_app_hard=.env* *.pem keys/* secrets/*
PROJ_my_app_soft=Dockerfile docker-compose.yml package.json package-lock.json

How dispatch works

Phases (details in references/gates.md):

• implement — pick up to MAX_PARALLEL eligible Ready cards (project known, attempts < max), claim each (Ready → Claimed → In Progress), create the git worktree from base_ref (never HEAD), launch implementer agents in parallel via herdr, poll card state, then run gates G1–G4 and the report check.
• review — same pattern for Ready for Review cards, with the reviewer agent. APPROVE → Human Review; CHANGES REQUESTED → Ready (re-implementation reads the review comment).
• cleanup — remove worktrees + ai/<cardId> branches of Done cards.

Key design rule (learned the hard way — see references/lessons.md): agents never post their own report comments. The script checks after each run and auto-captures the agent's final transcript output from herdr if the comment is missing. The card move is the agent's only plnk mutation — and when the agent drops even that (turn ends, card unmoved), the dispatcher rescues: it detects the idle agent and completes the move from the transcript's verdict/status marker or the commit evidence (gates still apply).

Merging Human Review cards (operator close)

1. Work in the project's main checkout (PROJ_<name>_repo), never in a worktree. Commit or stash pending operator edits on main first — they collide mid-merge otherwise.
2. Merge the ai/<cardId> branches oldest-first: git merge --no-ff ai/<cardId> -m "Merge ai/<cardId>: <title> (Planka #<cardId>)".
3. Resolve conflicts, then run the FULL test suite on main before pushing. Expect cross-branch assertion failures: one branch's tests can assert a code rule (e.g. no-sed) that another branch's code violates. Fix the product code to satisfy both (pure-bash equivalent), not the assertion.
4. Push to the project's forge remote — check git remote -v for the right remote name; never push to a GitHub upstream remote.
5. Post a merge-evidence comment per card (merge commit SHA, conflict resolutions, test status) and move it to $LIST_DONE; the next dispatch run's cleanup phase removes the worktrees and branches.

Merging early matters for in-flight cards: the dispatcher script executes from the main checkout, so merged dispatcher fixes take effect on later phases/runs even for branches based on older main (branch code is not rebased between attempts).

Other skills to use

• when planning workloads, specifications and tickets with the user load and use the grill-me skill

Prerequisites

• plnk CLI on PATH with valid token (plnk auth whoami)
• herdr server running (herdr status; start: nohup herdr server > /tmp/herdr-server.log 2>&1 &)
• run-pi-herdr.sh (herdr-cli skill) at $HERDR_RUN
• git, jq, flock

Troubleshooting

• dispatch.sh status shows cards stuck in Claimed/In Progress → a previous run was killed mid-flight; the next run will not pick them up (they are not in Ready). Inspect with herdr agent list, then move the card back to Ready manually (plnk card move <id> --to-list <readyListId>).
• Review/implementation keeps bouncing → read the card comments; the gate that failed is named in the bounce comment (G1/G2/G3).
• no eligible cards but there are cards in Ready → check the project field value matches a config key, and attempts < MAX_ATTEMPTS.
• G2 fails on a suite the change did not touch → run the exact gate command in a clean checkout of base_ref BEFORE re-dispatching: a pre-existing failure on main bounces every card regardless of content. Fix it inside the same ticket — amend the ticket body to explicitly authorize the minimal test change under Constraints. Do NOT file a separate fix ticket to wait on: worktree branches are not rebased onto a merged fix between attempts, so the gate keeps failing.
• Testing the branch while its card is in flight (live probes, manual runs) and finding defects → post them as an imperative card comment with exact repro commands AND amend the ticket body if the fix is required — re-dispatched implementers and reviewers read comments, but only the body is the contract.
• Never run dispatch.sh run in a foreground terminal call — a Hermes terminal timeout kills the script mid-poll: the launched herdr agent survives but the in-process rescue/gate logic dies, orphaning the In Progress card (the next cron run ignores it; phase_implement only reads Ready). Correct pattern: run in background with notify, OR after launching, attach your own watcher: poll plnk card get listId + herdr agent list status; if the agent ends idle without moving the card, apply rescue manually from STATUS.md verdict / commit evidence (gates still apply).
• Recovering a lost review verdict: the reviewer's pi session JSONL survives capture failure — find it under ~/.pi/agent/sessions/--workspace-worktrees-<project>-<cardId>--/*.jsonl by mtime window, then jq -r 'select(.type=="message") | select(.message.role=="assistant") | .message.content[]? | select(.type=="text" or .type=="thinking") | (.text // .thinking)' <file> | tail -80. If a text-only extraction returns empty, the agent ended its turn after moving the card without emitting a final message — the verdict lives in the thinking blocks (search them for "verdict"); the full issues list is almost always there. Post the recovered findings as an operator card comment ASAP — bounces with no findings send implementers hunting phantom issues.
• plnk env-var auth exists only in shells that source the config (set -a; source ~/.config/planka-development-flow/config.env; set +a). herdr agent sessions inherit the herdr server's env, not the dispatcher's — with no persisted credentials the implementer fails step 1 (card get) with AuthenticationFailed and burns an attempt in ~2 minutes (symptom: bounce with a report full of auth errors). One-time fix: persist the token in plnk's own credential store — plnk auth token set --server "$PLANKA_SERVER" "$PLANKA_TOKEN" (subcommand is token set; the token is a POSITIONAL arg, there is no --token flag on set). Verify agent-style: env -i HOME=$HOME PATH=$HOME/.local/bin:/usr/bin:/bin plnk auth status → authenticated: true, source: "config file". Field values: plnk card field list <card> (.data[] | .customFieldId/.content). Review-phase CHANGES bounces do NOT increment attempts (only gate bounces do).
• Log file for cron runs: ~/.config/planka-development-flow/dispatch.log — only cron appends there; a manual dispatch.sh run logs to stdout. So a card in In Progress (or a live herdr agent whose worktree cwd contains the card id) with no launched line in the log usually means a hand-run dispatch or an operator-reset Rejected card, not corruption. Card comments are the ground truth: operator notes and 🚀 Dispatched entries land there, not in the log.
• launch failed: no herdr workspace for impl-<cardId> → the launcher died before creating the session; read the named $LAUNCH_LOG_DIR/launch-impl-<cardId>.log. The card is bounced back to Ready instead of idling an hour in In Progress.
• Missing auto-captured report → the herdr read failed and the pi session fallback found nothing; dispatch.sh test-capture <worktree> exercises the same fallback (session dir is ~/.pi/agent/sessions/--<path-with-dashes>--).

Extending

This skill is the home of the system. When improving it:

• prompt changes → scripts/prompts/{implementer,reviewer}.txt
• new gates/phases → scripts/dispatch.sh (document in references/gates.md)
• new repo → add PROJ_<name>_* keys to the config
• keep the core rule: deterministic work in the script, fuzzy work in agents