API-Docker

 view release on metacpan or  search on metacpan

misc/agent-context/.claude/skills/kanban-issues-karr-coordination/SKILL.md  view on Meta::CPAN

---
name: kanban-issues-karr-coordination
description: Use when reading a karr board, picking or claiming cards, creating cards, handing cards to subagents, filing on another repository's board, or configuring and syncing karr. For working one card you were handed: kanban-issues-karr-ticket.
---

# karr — Kanban Assignment & Responsibility Registry

Git-native kanban board for multi-agent work. The board is the repository's
`refs/karr/*`: commands read and write those refs directly and sync them with
the remote; nothing lands in the work tree. In prose (commit subjects, card
bodies) a card is `k12`, never `#12` — the forge resolves `#12` against its
own issue 12. Commands take `k12` as well as `12`.

## Name yourself once

```bash
export KARR_CLAIM=$(karr agent-name)     # the checkout's directory name, e.g. "karr"
```

Claims are matched by name: `--claim` stamps it, `handoff` checks it,
`list --claimed-by` selects on it. Export `KARR_CLAIM` once per session and
leave `--claim` off: `pick`, `handoff` and `list --claimed-by` default to it,
and `move` and `edit` know a card you hold by it. `create`, `move` and `edit`
write it onto a card only when the card ends up in a `require_claim` column:
filing a card, promoting it to `todo` or adding a note leaves it free.
`archive` and `delete` ignore it — a card you hold needs `--claim NAME` there.
An explicit `--claim NAME` still wins. Agents in separate worktrees already
differ by name; several agents in the **same** directory take
`karr agent-name --unique` (`karr-8fa`).

## The board is the exchange — keep it pushed

Other agents, sessions and machines see a card only once it is on the remote;
one that stays local does not exist for them. So every mutating command pulls
first and pushes `refs/karr/*` after, and that is the point of the board, not a
side effect: never ask before a board write, never save findings up for later.
The push is not a publish-gate action, and a "don't push" in a plan or brief
means commits and tags, not the board. `--local-only` is for a configured remote
that cannot be reached, never for avoiding the push; `karr sync` publishes what
it wrote once the remote answers again. A push that fails (credentials,
rejected) goes at the top of your report — not into a sub-bullet, and not
a reason to stay local for the rest of the session. Card text is as public as
the repository: no secrets, no home-directory paths.

## Read the board

```bash
karr list --compact                      # open cards, one line each
karr board                               # per-column summary; --done shows the final column too
karr show 12                             # one card in full, body included
karr list --unclaimed --status todo      # todo cards no live claim holds
karr list --blocked                      # what is stuck, and why
karr show --me                           # the card you last touched (re-orient)
```

`list` hides the final column (`done`) and the archive unless asked for by
name (`--status done`, `--archived`).

## Hand out and close cards

The coordinating agent picks and claims; whoever does the work gets the card id
and works it with skill `kanban-issues-karr-ticket` — load both when you work a
card yourself.

```bash
karr pick --status todo --move in-progress       # most urgent free card, claimed as $KARR_CLAIM
karr move 12 in-progress                         # or take a specific one
karr move 12 in-progress --claim NAME            # explicit claim, wins over KARR_CLAIM
karr list --status review                        # what workers handed back
karr edit 12 --release && karr move 12 done      # close it once the work is committed
```

Columns with `require_claim` (`in-progress`, `review` on a default board)
refuse a move without a claim. A claim expires after `claim_timeout` (default
1h) and the card is free again; `pick` skips blocked cards and live claims.

`backlog` is held back: `pick` and karr-foundation never take a card from it
(`pick --status backlog` exits 2), and it holds no claim (`--claim` there is
refused; moving a card into it releases the claim). `todo` is the pool.
Promoting a card out of backlog (`karr move ID todo`) is the maintainer's
call, not a coordinating agent's: leave backlog alone unless told to promote.



( run in 1.677 second using v1.01-cache-2.11-cpan-1bcd28dbaf1 )