view release on metacpan or  search on metacpan

ex/README.md  view on Meta::CPAN

reported, but the command still exits `0` — a machine that has four of six
repositories of a fleet has an honest report to give about the four, and
aborting at the first unresolvable name would give none at all.

### The activity log

Every writing operation leaves a line in `refs/karr/log/<role>/<email>`. The
key is role-qualified — role `user` or `agent` — so that a human and an AI
sharing a Git configuration stay separate. That isn't cosmetics:
`karr-foundation` sets `KARR_ROLE=agent` for agent runs and `KARR_ROLE=hook` for
the domain hook, and exactly by that it later recognizes whether an agent has
touched a card (see "Stall" in section 4).

```bash
karr log                      # die 20 jüngsten Einträge
karr log --agent agent-fox    # was dieser Claim-Name getan hat
karr log --task 12 --last 50  # was mit dieser Karte passiert ist
```

### `context` and `metrics`

`karr context` builds a concise board summary for embedding into agent context
files like `AGENTS.md`. Sections are `in-progress`, `blocked`, `overdue`,
`recently-completed` and `activity`, selectable via `--sections`. `--write-to
FILE` replaces the content between the sentinels `BEGIN kanban-md context` and
`END kanban-md context`, or appends the block when the sentinels are missing.

A detail that reveals the intent: the `activity` section shows **only the
entries of other identities**, bounded by `--activity-limit` (default 5). An
agent reading its own briefing already knows what it has done itself — that's
what `karr show --me` is for. What belongs in a briefing is what everyone
*else* has done.

`karr metrics` reports flow metrics, exclusively from the lifecycle stamps
`created`, `started` and `completed`: throughput over 7 and 30 days (fixed
windows, like in `kanban-md`, so both tools mean the same thing), mean lead time
(`completed - created`), mean cycle time (`completed - started`), flow
efficiency and the cards running too long (started, not terminal, no
completion, oldest first). Archived cards never count.

Two details that put honesty before polish. Lead time is **never capped**: a
board with day-granular stamps can produce negative samples, and how many there
are is reported alongside as `negative_lead_samples`, instead of silently
pulling them to zero. And flow efficiency is computed over the cards that
contributed to *both* means, and over their own lead time — that's the one
deliberate deviation from `kanban-md`, which divides the mean cycle time by the
mean lead time, even when the two means were formed over different populations.
Where every finished card has a usable start, the same comes out; where not,
`kanban-md`'s definition can report an efficiency above 100%, and that describes
nothing.

### Board administration

```bash
karr config                    # zusammengeführte Einstellungen ansehen
karr config get foundation.enabled
karr config set foundation.enabled false
karr config --defaults         # die eingebauten Vorgaben statt dieses Boards

karr sync                      # refs/karr/* explizit holen und pushen
karr backup > karr-backup.yml  # ganzes Board als YAML
karr restore --yes < karr-backup.yml
karr destroy --yes
```

`karr sync` synchronizes `refs/karr/*` with the remote — without flags first
fetch, then push, plus one delete refspec for each ref that this clone has
deleted and not yet published (read off the tombstones under
`refs/karr-local/deleted/`). The push does **no prune**: a remote ref this clone
has never seen is another agent's card and not leftover — pruning it is the way
a card has actually been lost once.

After that, the same command does the same for `refs/karr-foundation/*`, the
shared namespace of `karr-foundation` (chain, run logs, questions mailbox). One
command for both, because a second one would be a second thing you could forget
— and the forgetting would be silent. The board half runs first, and the fleet
half never alone: the board identity and wipe refusals are what protects the
fleet refs against a swapped remote, because this namespace has none of its own.

`restore` is deliberately destructive — it first deletes the current
`refs/karr/*` and then plays in the snapshot. `destroy` removes the board
completely. If a remote exists, both also prune there.

### Helper refs

Not every shared state is a card. `karr set-refs` and `karr get-refs` put
arbitrary payloads into refs outside of `refs/karr/*`:

```bash
karr set-refs superpowers/spec/1234.md draft ready
karr set-refs superpowers/spec/1234.md < design.md    # mehrzeilig über stdin
karr get-refs superpowers/spec/1234.md
```

The arguments after the ref are joined with a space, so they're a single-line
payload. A document comes via stdin: without a content argument, `karr set-refs
REF < file` stores the file verbatim, and `karr get-refs REF > file` returns it
unchanged. Good for planning blobs, generated specs, agent scratch state,
workflow metadata you want synced through Git without modeling it as a card.

Protected namespaces are locked: branches, tags, remotes, stash, `refs/karr/*`
and `refs/karr-local/*` (where `karr pick` keeps its process-local locks).
`refs/karr-foundation/chain/*`, `.../log/*` and `.../questions/*` are
**read-only** for `set-refs` — those are written by `karr-foundation` with
schema and compare-and-swap — while `get-refs` reads them freely. That's exactly
how you look at a step, a run log or a question.

### Skills

The distribution ships a `karr` skill, installable locally in the repository or
globally in the home directory:

```bash
karr skill install
karr skill install --agent claude-code
karr skill install --agent codex --global --force
karr skill check --global
karr skill update
```

Targets are `claude-code`, `codex` and `cursor`.