view release on metacpan or search on metacpan
.claude/agents/karr-ref-worker.md view on Meta::CPAN
---
name: karr-ref-worker
description: "App::karr Git/ref storage worker â Git::Native and CLI fallback, refs-backed BoardStore persistence, CAS, locks, sync lifecycle, encoding boundaries, backup/restore, materialize/import, repair, and helper refs. Leaves a commit-ready t...
model: inherit
tools: Read, Edit, Write, Bash, Glob, Grep
briefing:
skills:
- getty-perl-core
- getty-perl-moo
---
You are the Git/ref persistence worker for **App::karr**. You own the path from an in-memory
board operation to durable `refs/karr/*` state and remote synchronization. Apply the loaded
conventions silently.
## Territory
- `lib/App/karr/Git.pm`, `BoardStore.pm`, `Lock.pm`, `SyncGuard.pm`, and `Encoding.pm`
- `Role/BoardDiscovery.pm`, `BoardAccess.pm`, and `SyncLifecycle.pm`
- storage/transport commands: `init`, `sync`, `materialize`, `import`, `repair`, `backup`,
`restore`, `destroy`, `get-refs`, `set-refs`, and `unlock`
- skill installation plumbing in `Cmd/Skill.pm`, `Cmd/Init.pm` and `Role/SkillFile.pm`, and
the shipped skill directories `share/kanban-issues-karr-coordination/` and
`share/kanban-issues-karr-ticket/`
Preserve these invariants: canonical board state is refs-first; the file tree is only a
materialized view; concurrent writes use the established CAS/lock path; native Git handles
local operations while the CLI fallback exists for transport compatibility; characters stay
inside and octets cross only through `App::karr::Encoding`.
.claude/rules/karr-rules.md view on Meta::CPAN
- **You can spawn subagents** (orchestrating main agent): Do NOT touch behavior-relevant karr
code yourself â delegate to the domain worker below. Your lane: coordinate, inspect, plan, review diffs,
run tests, edit non-behavioral docs. Why: only the `karr-*` agents get their skills
force-loaded via `briefing.skills`; you get no briefing and would touch internals with too
little context. Specialist lanes:
| Task | Agent |
|---|---|
| Task/config semantics, lifecycle, claims, dependencies, activity log, ordinary board commands, filtering, rendering, `context`, `metrics` | `karr-board-worker` |
| Git transport, refs-backed persistence, CAS, locks, sync, encoding, `init`/`sync`/`materialize`/`import`/`repair`/`backup`/`restore`/`destroy`/`unlock`, share-file plumbing | `karr-ref-worker` |
| karr-foundation: multi-board discovery, overview, agent command resolution, drain loops, `.karr.lock`/`.karr.state`, cooldown, stall detection, auto-blocking, `disable`/`enable` | `karr-foundation-worker` |
| Behavior-relevant code that spans those domains, or none of them cleanly | `karr-worker` (generalist fallback) |
| Write/extend tests under `t/` | `karr-test-writer` |
| Commits, `Changes`, card â done, pre-release audit | `karr-release-manager` |
| Docs: POD, README, `CONTEXT.md`, ADRs, shipped skills; doc audits | `karr-doc-writer` |
Pick the narrowest domain worker that covers the task â they brief on one domain instead of
the whole distribution, and each one names the other two in its own boundaries section, so a
task that turns out to belong elsewhere gets handed back rather than solved from the wrong
context. `karr-worker` stays for work that genuinely crosses the seams.
.claude/skills/kanban-issues-karr-coordination/SKILL.md view on Meta::CPAN
the board name to a directory by that basename (from `--board NAME=PATH` or the
fleet config) â a clone parked anywhere else is a card no one can trace back.
A fresh `git clone` carries no `refs/karr/*`, but `create` pulls the board
first (it is a mutating command), so the new id continues the remote's count â
no separate `karr sync --pull`. To record the new card as
something work *here* waits on, escalate it â
[references/cross-board.md](references/cross-board.md).
## Output flags
`--json` is taken by every board command, not by `backup`, `restore`,
`destroy`, `sync`, `set-refs`, `get-refs`. `--compact` exists on exactly nine:
`board`, `config`, `context`, `dashboard`, `list`, `log`, `metrics`, `pick`,
`show` â anywhere else it is `Unknown option: compact`, exit 2.
## When you need more
| Need | Read |
|---|---|
| Every option of `create`, `show`, `move`, `edit`, `delete`, `archive`; dependency rules | [references/cards.md](references/cards.md) |
| `list` filters and sorting, `board`, `dashboard`, `log`, `metrics`, `context --write-to` | [references/queries.md](references/queries.md) |
| `pick` ordering, `handoff` options, `unlock` for stale locks, timeouts, several agents on one board | [references/claims.md](references/claims.md) |
| A card waits on another repository: `--needs BOARD#ID`, `--escalated-from`, `karr needs --resolve` | [references/cross-board.md](references/cross-board.md) |
| `config get/set`, writable keys, the config YAML, `disable`/`enable` for karr-foundation | [references/config.md](references/config.md) |
| `sync`, fresh clones, stored card format, `materialize`/`import`, `repair`, `backup`/`restore`/`destroy`, `set-refs`/`get-refs` | [references/storage.md](references/storage.md) |
| `init`, `skill install/check/update`, `completion`, Docker | [references/setup.md](references/setup.md) |
.claude/skills/kanban-issues-karr-coordination/references/storage.md view on Meta::CPAN
karr repair # report what would change
karr repair --yes # migrate
```
Boards written by karr 0.402 or earlier stored UTF-8 double-encoded; they are
repaired on read meanwhile, and this migrates the refs once. It also raises a
`started` stamp written as a bare date (before k68) up to the card's own
`created` â the dry run says how many cards. `completed` stamps with the same
problem are reported, not touched.
## backup / restore / destroy
```bash
karr backup > karr-backup.yml
karr backup --output karr-backup.yml
karr restore --yes < karr-backup.yml # replaces the whole refs/karr/* namespace
karr restore --yes --input karr-backup.yml
karr destroy --yes # deletes refs/karr/* here AND on the remote
```
`restore` and `destroy` are destructive; take a `backup` first.
## Helper refs
```bash
karr set-refs superpowers/spec/1234.md draft ready # arguments joined with one space: a one-line payload
karr set-refs superpowers/spec/1234.md < design.md # no content argument: stdin, stored verbatim
karr get-refs superpowers/spec/1234.md > design.md # back unchanged
```
Shared payloads in Git refs outside the protected namespaces (`refs/karr/*`,
.claude/skills/karr-single-binary/references/pp-recipe.md view on Meta::CPAN
## 3. Verify
```bash
PAR_GLOBAL_TEMP="$(mktemp -d)" ./karr --help # fresh cache, first-run extract
# then exercise EVERY subcommand against a throwaway board (trap 1 dies at runtime)
```
Exercise the subcommands in a **separate `mktemp -d` + `git init` repo**, never in
the karr checkout â a worktree shares `refs/karr/*` with the real board, so a
verification `create`/`move`/`destroy` there mutates live state. `karr <cmd> --help`
for each of the 32 commands is the cheap trap-1 probe (forces the class to load,
no side effects); pair it with one real initâcreateâlistâmoveâhandoffâbackupâ
restoreâdestroy flow to prove libgit2/FFI end-to-end.
Also run `karr skill install --agent claude-code` in a fresh `mktemp -d` project
and byte-compare what it wrote against the checkout's own `share/*/SKILL.md`
(and `references/*.md`) â the missing-`share/` `-a` trap above is invisible to
every check so far, since nothing above it reads the skill files, only loads
the class. `scripts/verify-binary.sh`'s trap 3 is exactly this install-and-diff.
Finally `scripts/check-binary-libs.sh ./karr`: none of the runs above can see a
lib the target lacks, because they run where it is installed. This one reads
Engineering discipline, the delegation lane, board coordination, and the release policy live in
`.claude/rules/karr-rules.md` â auto-loaded by Claude Code at launch. Don't restate them here.
**Delegate behavior-relevant code instead of editing it yourself** (the rule and rationale are in
the rules file). Agents in this repo (skills force-loaded via `briefing.skills`):
| Task | Agent |
|---|---|
| Task/config semantics, lifecycle, claims, dependencies (`needs`/`CrossBoard`), activity log, ordinary board commands, filtering, rendering | `karr-board-worker` |
| Git transport, refs-backed storage, CAS, locks, sync, encoding, materialize/import/backup/restore | `karr-ref-worker` |
| karr-foundation: discovery, drain loops, per-repo lock/state, cooldown, auto-blocking, `disable`/`enable` | `karr-foundation-worker` |
| Behavior-relevant code spanning those domains, or none of them cleanly | `karr-worker` (generalist fallback) |
| Write/extend tests under `t/` | `karr-test-writer` |
| Commits, `Changes`, card â done, pre-release audit | `karr-release-manager` |
| Docs: POD (`=attr`/`=method`, `# ABSTRACT`), README, `CONTEXT.md`, ADRs, shipped skills; doc audits | `karr-doc-writer` |
Take the narrowest domain worker that fits; each names the other two in its boundaries section
and hands a misrouted task back rather than solving it from the wrong context.
**Dogfood:** karr tracks its own work on its own board (`refs/karr/*`). Use `karr list --compact`
| `metrics` | implemented | `metrics` |
| `log` | implemented | `log` |
| `config` | implemented | `config` |
| `context` | implemented | `context` |
| `agent-name` | implemented | `agent-name` |
| `skill` | implemented | `skill` |
| `materialize` | implemented | â (refsâfiles bridge) |
| `import` | implemented | â (filesârefs bridge) |
| `repair` | implemented | â (migrates a 0.402-or-earlier board off double-encoded UTF-8) |
| `sync` | implemented | â (explicit refs pull/push) |
| `backup` | implemented | â (board snapshot to YAML) |
| `restore` | implemented | â (snapshotârefs, destructive) |
| `destroy` | implemented | â (remove `refs/karr/*` incl. remote) |
| `set-refs` / `get-refs` | implemented | â (helper refs outside the board) |
| `disable` / `enable` | implemented | â (board-level opt-out from karr-foundation runs) |
## Key design decisions
- **MooX::Cmd** for subcommand dispatch (not App::Cmd â lighter, Moo-native)
- **MooX::Options** for CLI option parsing
- **YAML::XS** for frontmatter (fast, correct YAML parsing)
rows under a heading per group; `--json` and `--compact` win over
it, so it changes only the table.
- A `--no-color` flag sits beside the `NO_COLOR` variable, available
both as `karr --no-color board` and `karr board --no-color`; colour
is on only when stdout is a terminal, `NO_COLOR` is unset, and
neither disabled it.
- Documentation brought back in line with the CLI. README and the
bundled skill claimed `--json` on every board command; `create`,
`init`, `agent-name`, `sync` and the payload commands (`backup`,
`restore`, `destroy`, `set-refs`, `get-refs`) do not take it, and
both texts now say which. The
skill still described commands materializing a temporary file view
while they run, which predates refs-first storage: commands read
and write the refs directly, and `karr materialize` is the only
thing that writes a file view. Its stored-card example gained the
frontmatter fences and `lock_timeout`. README's "what is built"
table said a chain could not be written from the CLI, two sections
after showing `karr-foundation plan` doing exactly that; that
table, the refs table and the option reference now name `plan` and
unchanged and remains the one command that may stamp an existing board,
because it is the one that rewrites every ref.
- "No karr board found. Run 'karr init' to create one." no longer speaks
for two different repositories (ticket k133). Write commands raised it
whenever `refs/karr/config` was absent, including on a repository whose
tasks, counter and log were all there â so a board missing exactly one
ref reported itself as never having existed. An agent hit that on a
repository holding 21 tickets, believed them gone, and ran `karr init`,
which at the time also broke how they were read (k132 above). A
repository with nothing under `refs/karr/` still gets the old sentence,
the one `backup`, `destroy`, `materialize` and `repair` raise for the
same state. A half-board now gets its own: it is named as one, the number
of task refs at stake is stated, and `karr init` is described as
completing the board while keeping what is already there. `karr init`
likewise reports which of the two things it did.
- `karr config get statuses` and `karr config get classes` are readable
again (ticket k130). Both lists allow an entry to be either a bare name or
a mapping â `{ name: in-progress, require_claim: true }`,
`{ name: expedite, wip_limit: 1 }` â and the renderer joined the raw list,
so every mapping printed as `HASH(0x558580cd1688)`. The default board hits
it twice in `statuses` and, because all four of its classes are mappings,
- Finished the sweep that stopped karr's own source locations reaching the
user (ticket k77). `croak` appends " at Some/Module.pm line 42." even to a
message that already ends in a newline, so anyone who ran `karr list`
outside a repository was told "Not a git repository. karr requires Git."
and then handed the file and line of the builder that said so; every
remote failure ended with a line number in whichever `Cmd/*` had called
the sync; and `karr-foundation` reported a broken config the same way.
Those, plus the pipe/fork/log-open failures in the foundation runner, now
go through `App::karr::Error::user_error` and print the message alone. The
four commands that let a Path::Tiny error out raw â `karr restore
--input` on an unreadable file, `karr backup --output` and `karr context
--write` into a directory karr may not write, `karr init --claude-skill`
into an unwritable `.claude` â now name the path the user typed and the
reason the OS gave, and nothing else. Two errors deliberately keep their
call site, because there it is the useful part: saving an unpersisted
ref-backed task, which is a programming error, and `croak` in
App::karr::Foundation's YAML report, whose parser message names its own
document, line and column and is passed through whole rather than reduced
to one line.
- A failed sync now shows git's error once instead of twice. The message
that ended the command embedded another copy of the multi-line error that
identity in `refs/karr/meta/board-id`. `karr init` and `karr
import` stamp it for boards they create (and never re-key an existing
one); a board from before this change is stamped by the first pull that
finds no id on either side, with the ordinary push path carrying the
stamp to the remote; a clone meeting a stamped remote for the first
time adopts that id. A pull where both sides have an id and they differ
is refused before any reconciliation, naming what happened and the two
ways through: `karr sync --push` to republish this board over the wrong
remote, or the new `karr sync --accept-foreign-board` to adopt the
remote's board. `karr restore` keeps the board's standing identity when
the snapshot predates the stamp, so restoring a backup onto its own
board never looks like a foreign takeover.
- Fixed `karr pick` being blind to a board imported from kanban-md. An
optional frontmatter field set to the empty string counted as set,
because a Moo predicate only knows whether the attribute was passed â
and `claimed_by: ""` is exactly what a kanban-md card carries once it has
been read and rewritten, or written by hand. `karr import` stored it
verbatim, `karr pick` read it as a claim by somebody, and so on a freshly
imported board pick answered "No available tasks to pick." while
`karr list` showed the very same work sitting in backlog. An empty
`claimed_by` is now no claim, the same test `karr move`/`edit`/`delete`
- Fixed `karr handoff` overwriting concurrent changes. It read the task,
changed it and saved it back without checking the card had not moved in
between, so a claim landing in that window was silently replaced instead
of obeyed. The handoff now goes through the same compare-and-swap and the
same status-change path as `karr move`, so the claim rule is applied to
the revision that actually gets written.
- Fixed `karr pick` locks being published to the remote. Lock refs lived at
`refs/karr/tasks/N/lock`, inside the namespace karr pushes, so any sync
that fired while a lock was held put it on the remote; other clones then
pulled a lock whose holder they could not see, could not outlive and
could only clear with `karr unlock`. Board backups snapshotted it too.
Locks are process-local state, so they now live under `refs/karr-local/`,
which nothing pushes, fetches, prunes or snapshots â and which
`karr set-refs` refuses, so no refspec can reach them at all. Board
state, including the `refs/karr/log/*` activity log, is unaffected and
still syncs. Locks left at the old address by an older karr, or pulled
from a remote that still has them, are not acted on â a lock from another
clone says nothing about this process â but `karr unlock` lists them,
marked as strays, and clears them.
- Fixed the last race in `karr delete`'s claim guard. `App::karr::Git`
could only delete a ref by name, through a libgit2 call that takes no
remote too, because the push insurance faithfully mirrored the
half-executed destruction. Every ref name is now validated and every
commit object built before the first ref moves, so a snapshot karr cannot
apply is refused with the board untouched, and the refs it can apply are
overwritten in place instead of starting from an empty namespace. The ref
updates themselves are still a loop rather than one transaction â an I/O
failure part-way through can still leave a board holding a mix of old and
new refs â but the board is no longer emptied before the first write, so
no failure can leave it with nothing in it. A snapshot may also no longer
address refs outside `refs/karr/`, which previously let a hand-edited
backup overwrite a branch.
- Fixed any write command silently seeding a partial board in whichever
repository it was run in, and that partial board then locking `karr init`
out of it for good â `karr create` typed in the wrong directory was
enough, and `karr destroy --yes` was the only way back. A board now
counts as existing only when `refs/karr/config` is present; the commands
that write to the board refuse with "No karr board found" when it is
absent, and `karr init` completes a half-board (keeping its ID counter,
so existing tasks are not overwritten) instead of refusing. `backup`,
`destroy`, `materialize` and `repair` still work on whatever is under
`refs/karr/`, so a half-board an older karr left behind can still be
inspected and removed. `karr import --yes` is still allowed to bootstrap
a board from a bare kanban-md `tasks/` view, and now writes the default
config ref when the view has no `config.yml`, so the board it leaves
behind is one the writing commands accept. The read-only commands
(`list`, `board`, `show`, `context`, `log`, `config get`) are unchanged:
they still report an empty board with the default config rather than
refusing.
- Fixed a ref deletion that did not happen reporting success. `delete_ref`
"waiting ---"` was enough, and YAML dumps such a value unquoted â cut the
frontmatter mid-line. Every command that loads the board then died with
"Missing required arguments: id, title", `delete` included, so the board
could not be repaired with karr at all. The parser now scans for `---` at
a line start, matching kanban-md.
- Fixed UTF-8 being encoded twice everywhere. karr passed YAML::XS::Dump
output (octets) around as characters, mixed that with character-level
file I/O, and never decoded `@ARGV`. Non-ASCII text was therefore stored
mojibaked in the refs, handed to agents mojibaked through `--json`,
written three encodes deep by `materialize`, and destroyed by
`backup`/`restore`; a correctly encoded kanban-md task file could not be
imported at all ("invalid trailing UTF-8 octet"). `karr show` looked
right only because two errors cancelled out. karr now keeps character
strings internally and encodes only at its edges â argv, stdout/stderr,
Git ref blobs, YAML and JSON â so non-ASCII titles, bodies, tags, and
board names round-trip and kanban-md interop works outside ASCII.
- Boards written by earlier versions keep working and are read correctly:
the double encoding is undone on load for any board without the new
`refs/karr/meta/encoding` marker. New command `karr repair` makes that
permanent â it reports by default, rewrites the affected refs with
`--yes`, and stamps the marker so nothing guesses at the board's bytes
results tail) and `Task->to_json_hash` (the frontmatter+body payload of
show/pick/handoff). The previously untested `--json` paths of
move/edit/show/pick/handoff are now pinned by tests.
- Internal refactor, no user-visible behavior change: the ~900-line
karr-foundation module is split along its natural seams into three
focused collaborators â `Foundation::Runner` (agent command execution
and common-error classification), `Foundation::State` (lock file, JSON
state, cooldown backoff, attempt counters) and `Foundation::Overview`
(the read-only dashboard) â with `Foundation` staying the orchestrator
and delegating, so every existing call site keeps working unchanged.
- `karr backup`, `karr restore` and `karr destroy` now run through the
shared sync lifecycle instead of hand-rolled pull/push calls, so the
most destructive commands get the same 3x pull/push retry and
push-on-crash insurance as every other mutating command (backup is
read-only and takes only the retrying pull â it never pushes).
- `karr config` and `karr skill` now accept options placed before the
action (`karr config --json show`, `karr skill --json install`) instead
of misreading the leading flag as the action ("Unknown action: --json").
Both commands read their action (and config's key/value) through the same
option-aware positional parsing the id-taking commands already use, now
extracted into a shared `App::karr::Role::CliArgs`. Surplus positionals
are rejected too: `karr skill` takes exactly the action, and `karr config`
enforces its per-action arity (`config get KEY extra` is rejected).
- Internal dead-code cleanup, no user-visible behavior change: remove the
libgit2; the scan-directory sweep additionally confirms the resolved
repository root is the scanned child itself, so a plain directory nested
inside a karr repo is not mistaken for a board.
- Fix the documented global `--dir` option being silently ignored:
commands always operated on the board of the current directory, so
`karr --dir /other/repo create "X"` quietly wrote to â and synced â
whatever board the caller happened to be standing in. `--dir` is now a
real option on every board command (`karr list --dir PATH`, the root
form `karr --dir PATH list`, and bare `karr --dir PATH` for the board
summary all work), seeding repository discovery before any store or
sync activity; init, backup, restore,
and destroy, which previously hardcoded the current directory, honor
it too. A `--dir` that does not lead to a Git repository fails loudly
instead of falling back to the current directory.
- Options may now be placed before, between, or after positional
arguments (`karr archive --json 1`, `karr handoff --claim tester 1`,
`karr edit --title New 3`), matching how the kanban-md CLI behaves.
Previously the raw option token was read as the task id, giving opaque
errors like "Task --claim not found" â and `karr show --last N` crashed
outright. The real positionals are now extracted from argv using each
command's own option metadata (value-taking options swallow their
- Skip user.email test gracefully when not configured
0.101 2026-03-23 03:02:05Z
- Strengthen docs and GitHub landing pages
- Add POD to all modules (bin/karr, BoardStore, commands, roles)
0.100 2026-03-23 01:50:27Z
- Migrate board state to git refs only (refs/karr/*), drop karr/ directory
- Add backup and restore commands for refs/karr snapshot export/import
- Add destroy command (remove all board refs, local and remote)
- Add set-refs / get-refs helper commands for arbitrary ref storage
- Add skill command with File::ShareDir-based skill loading
- Simplify board output and drop WIP limits from config
- Split Docker runtime images (slim + full) with entrypoint script
- Expand POD across Git.pm, Lock.pm, commands, and roles
0.003 2026-03-20 05:01:01Z
- Initial release: karr, a Git-ref-backed kanban board driven from a Perl
t/254-compact-output-role.t
t/255-config-show-defined-values.t
t/256-dashed-option-after-flag.t
t/26-skill-share-dir.t
t/260-context-write-to-with-output-flags.t
t/263-error-shows-working-command.t
t/264-working-command-frequent.t
t/266-dependency-check-coverage.t
t/268-create-init-agentname-json.t
t/269-claim-refusal-hint.t
t/27-backup-restore.t
t/270-create-claim-require-claim.t
t/271-list-pick-filter-validation.t
t/272-version-flag.t
t/273-edit-class-estimate-clear-due.t
t/275-list-claim-and-hidden-footer.t
t/276-command-help.t
t/277-completion.t
t/278-log-since-action.t
t/279-group-by.t
t/28-destroy.t
=head1 VERSION
version 0.602
=head1 SYNOPSIS
karr init --name "My Project"
karr create "Fix login bug" --priority high
karr move 1 in-progress --claim swift-fox
karr board
karr backup > karr-backup.yml
=head1 DESCRIPTION
F<karr> is the primary command line interface for L<App::karr>. It manages a
Git-native kanban board whose canonical state lives in C<refs/karr/*>, plus
optional helper payloads in non-protected refs outside that namespace.
Run it from inside a Git repository. Commands discover the repository root,
pull the current board refs, and read and write task cards directly against
those refs -- no board files ever touch the work tree for an ordinary
karr init --name "HandyIntelligence Prototype" --claude-skill
Claim and start the next task under this checkout's claim name:
export KARR_CLAIM=$(karr agent-name)
karr pick --move in-progress
Export the board before trying a destructive restore:
karr backup > karr-backup.yml
karr restore --yes < karr-backup.yml
=head1 SEE ALSO
L<App::karr>, L<App::karr::Task>, L<App::karr::BoardStore>,
L<App::karr::Git>, L<App::karr::Cmd::Init>, L<App::karr::Cmd::Skill>,
L<App::karr::Cmd::Backup>, L<App::karr::Cmd::Restore>
=head1 SUPPORT
=head2 Issues
docs/superpowers/plans/2026-03-22-ref-first-board-implementation.md view on Meta::CPAN
# Ref-First Board Implementation Plan
> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Replace the persistent `karr/` working tree with a Git-ref-first board model and add destructive backup/restore for `refs/karr/*`.
**Architecture:** Treat `refs/karr/*` as the sole source of truth. Read and write commands operate on ref-backed state, using temporary materialization only as an internal implementation detail. Config overrides live in `refs/karr/config`, the next n...
**Tech Stack:** Perl, Dist::Zilla, Git refs, YAML::XS, existing `App::karr::*` command modules, `Test::More`.
---
## Chunk 1: Ref-backed board storage
### Task 1: Add a board store abstraction
**Files:**
docs/superpowers/plans/2026-03-22-ref-first-board-implementation.md view on Meta::CPAN
- [ ] **Step 1: Add failing tests for write operations with no persistent `karr/` directory**
- [ ] **Step 2: Run `prove -l t/03-archive.t t/04-handoff.t t/16-pick-lock.t t/20-next-id-collision.t t/26-ref-first-writes.t`**
Expected: FAIL on direct file operations.
- [ ] **Step 3: Refactor each command to fetch refs, mutate ref-backed state, and push refs back**
- [ ] **Step 4: Move numeric id allocation to `refs/karr/meta/next-id`**
- [ ] **Step 5: Re-run the focused tests**
Expected: PASS.
## Chunk 4: Backup, restore, migration, and docs
### Task 7: Add backup and restore commands
**Files:**
- Create: `lib/App/karr/Cmd/Backup.pm`
- Create: `lib/App/karr/Cmd/Restore.pm`
- Modify: `lib/App/karr.pm`
- Modify: `bin/karr`
- Test: `t/27-backup-restore.t`
- [ ] **Step 1: Write failing tests for YAML backup, destructive restore, and `--yes` protection**
- [ ] **Step 2: Run `prove -l t/27-backup-restore.t`**
Expected: FAIL because the commands do not exist yet.
- [ ] **Step 3: Implement `backup` to emit all `refs/karr/*` as YAML to a file or stdout**
- [ ] **Step 4: Implement `restore` to require `--yes`, delete all current Karr refs, recreate the snapshot refs, and push them**
- [ ] **Step 5: Run `prove -l t/27-backup-restore.t`**
Expected: PASS.
### Task 8: Clean up docs, tests, and Docker skill behavior
**Files:**
- Modify: `README.md`
- Modify: `share/claude-skill.md`
- Modify: `lib/App/karr.pm`
- Modify: `lib/App/karr/Cmd/Init.pm`
- Modify: `lib/App/karr/Cmd/Skill.pm`
docs/superpowers/plans/2026-09-14-karr-binary-release.md view on Meta::CPAN
- Create: `scripts/verify-binary.sh`
**Interfaces:**
- Consumes: a built binary path (arg 1), produced by `scripts/build-binary.sh`.
- Produces: exit 0 iff every subcommand loads and a real libgit2 board flow succeeds. Task 3's CI job calls this before uploading.
**Notes:** Two traps only surface at runtime â a missing `Cmd::*` class (subcommand dies when first called) and a libgit2/FFI break (any board op dies). The verify must therefore load every subcommand and run one real board flow, in a throwaway rep...
- [ ] **Step 1: Confirm the exact subcommand list and flow signatures**
Run: `/tmp/karrbuild/karr --help` and, for the flow commands, `/tmp/karrbuild/karr create --help`, `move --help`, `handoff --help`, `backup --help`, `destroy --help`.
Expected: note the real flag names (e.g. how `create` reports the new id, the `destroy` confirmation flag). Use these exact forms in Step 2. The command list to load is the "Commands (current)" table in `CLAUDE.md`.
- [ ] **Step 2: Write `scripts/verify-binary.sh`**
```bash
#!/usr/bin/env bash
# Smoke-test a built karr binary against both pp runtime traps.
# Usage: verify-binary.sh <karr-binary>
set -euo pipefail
BIN=$(realpath "${1:?usage: verify-binary.sh <karr-binary>}")
export PAR_GLOBAL_TEMP="$(mktemp -d)"
"$BIN" --version
"$BIN" --help >/dev/null
# Trap 1: force every dynamically-loaded Cmd class to load (no side effects).
for cmd in init create list show move edit delete board dashboard pick unlock \
archive handoff needs metrics log config context agent-name skill \
materialize import repair sync backup restore destroy \
set-refs get-refs disable enable; do
"$BIN" "$cmd" --help >/dev/null || { echo "FAIL: subcommand $cmd" >&2; exit 1; }
done
echo "trap1 (subcommand classes): OK"
# Trap 2: a real libgit2/FFI round trip in a throwaway repo, never the checkout.
work=$(mktemp -d)
(
cd "$work" && git init -q .
"$BIN" init
"$BIN" create "smoke test card" >/dev/null
"$BIN" list --compact
id=$("$BIN" list --compact | awk 'NR==1{gsub(/#/,"",$1); print $1}')
"$BIN" move "$id" in-progress --claim smoke
"$BIN" handoff "$id" --claim smoke --note ok
"$BIN" backup > board.yaml && test -s board.yaml
)
echo "trap2 (libgit2 board flow): OK"
echo "verify: OK"
```
Then: `chmod +x scripts/verify-binary.sh`. Adjust the id-extraction and any flag to match what Step 1 showed.
- [ ] **Step 3: Run the verify against the locally built binary**
Run: `./scripts/verify-binary.sh /tmp/karrbuild/karr`
Expected: prints `trap1 ... OK`, `trap2 ... OK`, `verify: OK`, exit 0. A failure on a single subcommand means that `Cmd::*` class needs its namespace covered by a glob in `build-binary.sh` (it already uses `App::karr::Cmd::**`, so this should pass â...
docs/superpowers/specs/2026-03-22-ref-first-board-design.md view on Meta::CPAN
- reuse of existing task markdown format
- no persistent `karr/` directory
This is preferable to rewriting every command to manipulate raw YAML strings in
one step.
## Backup and restore
Add explicit snapshot commands:
- `karr backup [FILE|-]`
- `karr restore [FILE|-] --yes`
Backup writes a YAML snapshot of all `refs/karr/*`.
Restore is destructive by design. With `--yes`, it should:
1. fetch current refs
2. delete every existing `refs/karr/*`
3. recreate refs from the YAML snapshot
4. push the resulting ref set
Without `--yes`, restore must fail with a strong warning. The command should
make it obvious that refs missing from the backup will be removed.
## Skill installation and Docker
Skill installation must keep working when `karr` is run through Docker. The
important requirement is that the target `HOME` inside the container is the one
that actually contains mounted `.codex`, `.claude`, or `.cursor` directories,
and that the final process runs as a non-root user where appropriate.
This is separate from board storage, but it should be verified during the same
cleanup pass because the current vendor-style usage depends on it.
docs/superpowers/specs/2026-03-22-ref-first-board-design.md view on Meta::CPAN
- `next_id` needs atomic handling so concurrent `create` operations stay safe
- restore is intentionally destructive and needs strong UX guardrails
## Recommendation
Implement the ref-first architecture in stages:
1. introduce a ref-backed board store abstraction
2. move config and task loading off persistent `karr/`
3. make `init` Git-only and ref-only
4. add backup/restore
5. remove remaining local board assumptions from docs, tests, and help text
docs/superpowers/specs/2026-05-15-role-boardaccess-split-design.md view on Meta::CPAN
No `board_dir`, no temp dir, no task loading. Commands access tasks via `$store->load_tasks()`, `$store->save_task($task)`, etc.
### Role::SyncLifecycle
Provides:
- `sync_before()` â runs `git pull` with 3 retries and clear error messages on failure
- `sync_after()` â runs `git push` with 3 retries and clear error messages on failure
- Returns a `SyncGuard` object from `sync_before()` that acts as insurance: if `die`/`croak` happens before `sync_after` is called, the Guard's `DESTROY` runs `sync_after`
Commands explicitly call `sync_after()` after successful work. Guard is backup insurance only.
### SyncGuard
```perl
package App::karr::SyncGuard;
has git => (is => 'ro', required => 1);
has _errors => (is => 'ro', default => sub { [] });
has _done => (is => 'rw', default => 0);
docs/superpowers/specs/2026-05-15-role-boardaccess-split-design.md view on Meta::CPAN
die "Push failed after 3 attempts. Local refs are intact.\n"
. "Run 'karr sync' to retry.\n"
. "Errors: " . join(', ', $self->errs) . "\n";
}
```
Commands use:
```perl
sub execute {
my ($self, $args_ref, $chain_ref) = @_;
my $guard = $self->sync_before; # backup insurance
# ... command logic ...
# may die/croak, guard handles cleanup in DESTROY
$self->sync_after; # explicit call for clarity
undef $guard; # mark done, DESTROY no-ops
}
```
### No Materialized Temp Dir
docs/superpowers/specs/2026-09-14-karr-binary-release-design.md view on Meta::CPAN
Per target `<arch>` in `{x86_64, arm64}`, version `<v>` = tag without leading `v`:
- `karr-<v>-linux-<arch>` + `karr-<v>-linux-<arch>.sha256`
- `karr-<v>-linux-<arch>.tar.gz` + `karr-<v>-linux-<arch>.tar.gz.sha256`
Alongside the CPAN tarball + sha256 that `dzil` already attached.
### D. In-job verification (before upload)
The two `pp` traps only surface at runtime, so the job must exercise them:
- **Trap 1 (dynamic Cmd classes):** `karr <cmd> --help` for every subcommand
forces each `App::karr::Cmd::*` to load (no side effects).
- **Trap 2 (libgit2/FFI):** one real `init â create â list â move â handoff â
backup â restore â destroy` flow in a throwaway `mktemp -d` + `git init` repo
(never the checkout â its `refs/karr/*` is the live board), from a fresh
`PAR_GLOBAL_TEMP`, proving libgit2 resolves through the bundled share dir.
- Ideally the verify step runs in a **minimal container without dev libs** to
catch a missing transitive `.so` before release. At minimum, assert the
documented Runtime requirements libs are the only external deps (`ldd` /
runtime check).
## Runtime requirements (documented for downloaders)
The binary bundles the perl interpreter, karr's XS `.so`s, and libgit2's share
dir, but libgit2's `DT_NEEDED` libraries are resolved by the OS loader at
ex/README.md view on Meta::CPAN
### 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.
lib/App/karr.pm view on Meta::CPAN
[ archive => 'Archive a task (soft-delete)' ],
[ handoff => 'Hand off a task for review' ],
[ needs => 'Report or resolve cross-board dependencies' ],
[ destroy => 'Delete the entire refs/karr/* board' ],
[ config => 'View or modify board config' ],
[ disable => 'Disable automated agent runs on this board' ],
[ enable => 'Re-enable automated agent runs on this board' ],
[ context => 'Generate board context summary' ],
[ log => 'Show activity log' ],
[ metrics => 'Show flow metrics' ],
[ backup => 'Export refs/karr/* as YAML' ],
[ restore => 'Replace refs/karr/* from YAML' ],
[ materialize => 'Write refs/karr/* out as a tasks/ file view' ],
[ import => 'Import a tasks/ file view into refs/karr/*' ],
[ repair => 'Migrate a 0.402-or-earlier board off double-encoded UTF-8' ],
[ sync => 'Sync board with remote' ],
[ 'agent-name' => 'Print the claim name for this checkout' ],
[ skill => 'Install/update agent skills' ],
[ 'set-refs' => 'Store helper payloads in a Git ref' ],
[ 'get-refs' => 'Fetch and print helper payloads from a Git ref' ],
[ completion => 'Generate shell completion scripts' ],
lib/App/karr.pm view on Meta::CPAN
# and anywhere else it is an unknown option that exits 2 (#254). The old
# parenthesis named two of them and read like a shortened list.
$out .= " --compact Compact output (board, config, context, dashboard,\n";
$out .= " list, log, metrics, pick, show)\n";
$out .= "\n" . colored("EXAMPLES:", 'bold') . "\n";
$out .= " karr init --name \"My Project\"\n";
$out .= " karr create --title \"Fix login bug\" --priority high\n";
$out .= " karr list --status todo,in-progress\n";
$out .= " karr move 1 in-progress --claim agent-fox\n";
$out .= " karr pick --claim agent-fox --move in-progress\n";
$out .= " karr backup > karr-backup.yml\n";
$out .= " karr restore --yes < karr-backup.yml\n";
$out .= " karr set-refs superpowers/spec/1234.md draft ready\n";
$out .= " karr board\n";
$out .= "\nRun " . colored("karr <command> --help", 'bold') . " for command-specific options.\n";
# Exit-code contract (ADR 0002): a positive code here is a usage/option-parse
# error from MooX::Options (unknown option, bad value on the root command), so
# normalize it to 2. Help requests (-h/--help) arrive with code 0 -> exit 0.
# A negative code means "print, do not exit" and is left untouched.
$code = 2 if $code > 0;
lib/App/karr.pm view on Meta::CPAN
The installed executable is L<karr>. Running C<karr> without a subcommand shows
the board summary by default, and the command-specific modules under
C<App::karr::Cmd::*> implement the individual operations.
Use L<karr> when you want to learn:
=over 4
=item * which command to run for a task
=item * how backup, restore, destroy, and helper refs fit together
=item * which module implements each subcommand
=item * how to use the Docker-wrapped CLI day to day
=back
=head1 DOCKER RUNTIME
Perl installation remains the normal development path, but Docker is a
lib/App/karr/BoardStore.pm view on Meta::CPAN
my $whole = $store->board_exists;
Callers state the refusal through L<App::karr::Role::BoardDiscovery/require_board>
rather than testing this themselves: a repository that fails this check may
still hold a half-board's tasks, and the two cases need different words (#133).
=head2 has_board_refs
True when anything at all lives under C<refs/karr/>, initialized board or not.
This is the question the commands that clean up or read raw refs
(C<backup>, C<destroy>, C<materialize>, C<repair>) actually have: refusing them
on a half-board would strand the refs a pre-fix karr already left behind, with
no way to remove them from inside karr.
my $anything_here = $store->has_board_refs;
=head2 load_config_overrides
Returns the board's raw config overrides -- whatever C<refs/karr/config>
currently holds, decoded but not merged with the code defaults. A board with
no config ref yet, or one whose ref does not decode to a mapping, answers
lib/App/karr/BoardStore.pm view on Meta::CPAN
L</stamp_encoding_version>.
$store->serialize_from( $git_root );
=head2 snapshot
Reads every ref under C<refs/karr/> into a plain hash reference:
C<< { version => 1, refs => { $ref_name => $content, ... } } >>, where
C<$content> is that ref's raw stored text (config YAML, a task's Markdown
document, or a bare id/hex string for the meta refs) via
L<App::karr::Git/read_ref>. C<karr backup> writes this straight to YAML; pair
with L</restore_snapshot> to write one back onto C<refs/karr/*>.
my $snapshot = $store->snapshot;
=head2 restore_snapshot
Makes the board consist of exactly the refs in the snapshot. Every ref name is
checked and every commit object built before the first ref moves, so a snapshot
karr cannot write is refused with the board untouched instead of destroying it
on the way through (#47). See L<App::karr::Git/replace_board_refs>.
lib/App/karr/Cmd/Backup.pm view on Meta::CPAN
# ABSTRACT: Export the ref-backed karr board as YAML
package App::karr::Cmd::Backup;
our $VERSION = '0.602';
use Moo;
use MooX::Cmd;
use MooX::Options (
usage_string => 'USAGE: karr backup [--output PATH]',
);
use Path::Tiny;
use App::karr::Encoding qw( yaml_dump );
use App::karr::Error qw( user_error clean_error command_hint );
use App::karr::Role::BoardDiscovery;
use App::karr::Role::CliArgs;
use App::karr::Role::SyncLifecycle;
with 'App::karr::Role::BoardDiscovery';
with 'App::karr::Role::SyncLifecycle';
lib/App/karr/Cmd/Backup.pm view on Meta::CPAN
# CLI's :encoding(UTF-8) layer encodes for stdout. A Dump() here would emit
# octets and both paths would encode them a second time (ticket #53).
my $yaml = yaml_dump( $store->snapshot );
if ( $self->output ) {
my $file = path( $self->output );
# An --output karr cannot write is the user's path, not karr's: Path::Tiny
# would otherwise report this file and line at them (#77).
eval { $file->parent->mkpath; $file->spew_utf8($yaml); 1 }
or user_error( "Could not write $file: ", clean_error($@) );
print STDERR "Wrote backup to $file\n";
return;
}
print $yaml;
}
1;
__END__
lib/App/karr/Cmd/Backup.pm view on Meta::CPAN
=head1 NAME
App::karr::Cmd::Backup - Export the ref-backed karr board as YAML
=head1 VERSION
version 0.602
=head1 SYNOPSIS
karr backup > karr-backup.yml
karr backup --output karr-backup.yml
=head1 DESCRIPTION
Exports the complete C<refs/karr/*> namespace as a YAML snapshot. The default
mode writes the snapshot to standard output so it can be redirected or piped.
Use C<--output> when you want C<karr> to write the file directly.
=head1 OPTIONS
=over 4
lib/App/karr/Cmd/Restore.pm view on Meta::CPAN
my $content = eval { path( $self->input )->slurp_utf8 };
defined $content
or user_error( "Could not read ", $self->input, ": ", clean_error($@) );
return $content;
}
# STDIN is the one input edge App::karr::Encoding leaves without a PerlIO
# layer, precisely so this decode is explicit and happens exactly once.
binmode STDIN, ':raw';
my $content = do { local $/; <STDIN> };
die "No backup payload received on stdin\n"
unless defined $content && length $content;
return from_octets($content);
}
1;
__END__
=pod
lib/App/karr/Cmd/Restore.pm view on Meta::CPAN
=head1 NAME
App::karr::Cmd::Restore - Restore the ref-backed karr board from YAML
=head1 VERSION
version 0.602
=head1 SYNOPSIS
karr restore --yes < karr-backup.yml
karr restore --yes --input karr-backup.yml
=head1 DESCRIPTION
Replaces the complete C<refs/karr/*> namespace with a previously exported YAML
snapshot. This is intentionally destructive: refs currently present but absent
from the snapshot are deleted as part of the restore.
It is not destructive on the way in, though. Every ref name in the snapshot is
checked and every commit object written before the first ref moves, so a
snapshot karr cannot apply -- an unusable ref name, or one outside
lib/App/karr/Git.pm view on Meta::CPAN
return () unless $self->write_ref_cas( NEXT_ID_REF, ($id + 1) . "\n", $oid );
return $id;
} );
}
# ----- Whole-board replacement (restore) -----
# The mirror image of validate_helper_ref, which keeps helper refs out of the
# board namespace: a snapshot may only address refs inside it. Without this a
# hand-edited backup could point refs/heads/main at a parentless karr commit,
# because restore fed whatever keys the YAML carried straight to
# reference_create.
sub validate_board_ref {
my ( $self, $ref ) = @_;
defined $ref && length $ref
or die "karr: snapshot contains a ref with no name\n";
die "karr: '$ref' is outside the board namespace " . BOARD_ROOT . "\n"
unless index( $ref, BOARD_ROOT ) == 0;
die "karr: '$ref' is not a valid git ref name\n"
unless Git::Native->reference_name_is_valid($ref);
lib/App/karr/Git.pm view on Meta::CPAN
remote's value.
=head2 validate_board_ref
my $ref = $git->validate_board_ref($ref);
The mirror image of L</validate_helper_ref>: dies unless C<$ref> is
non-empty, inside the board namespace C<refs/karr/>, and a syntactically
valid git ref name. Returns C<$ref> unchanged on success.
L</replace_board_refs> (C<karr restore>) validates every ref in a snapshot
through this before writing anything, so a hand-edited backup can't point a
ref like C<refs/heads/main> at a board commit.
=head2 replace_board_refs
$git->replace_board_refs( \%refs ); # { $ref => $content, ... }
Makes the board consist of exactly the given refs: C<karr restore>'s
primitive. Every ref name is validated (L</validate_board_ref>) and every
commit object built I<before> any ref is touched, so a single bad name or
non-text value in C<%refs> dies without leaving the board half-overwritten.
lib/App/karr/Lock.pm view on Meta::CPAN
Lock refs live under C<refs/karr-local/>, which nothing pushes, fetches, prunes
or snapshots. A lock says "this process, in this clone, is mid-pick right now",
and that sentence has no meaning anywhere else: a clone that receives one cannot
tell whether the holder is still alive, and has no way to find out.
They used to live at C<refs/karr/tasks/N/lock>, inside the namespace C<karr>
pushes. Any sync that fired while a lock was held published it, other clones
pulled it, and it then blocked their picks until somebody ran C<karr unlock> --
a lock that outlived the process holding it and the machine it ran on (#93). It
also turned every board backup into a snapshot of somebody's momentary lock.
Moving the refs out is what makes that impossible, rather than making it depend
on the timing of when a lock happens to be released.
Locks left in the old place by a C<karr> older than this one -- or pulled from a
remote that still has them -- are not acted on: they cannot say anything about
this process, and a pick's exclusivity does not rest on them anyway. They are
not ignored either. C<locks> reports them, marked C<legacy>, and C<break_lock>
clears them, so C<karr unlock> is the way out of the mess the old layout left
behind.
lib/App/karr/Role/BoardDiscovery.pm view on Meta::CPAN
unrelated repository -- and that partial board then locked C<karr init> out of
it permanently (#62).
It distinguishes the two ways of not having a board, because they call for
different things from the reader (#133):
=over 4
=item * nothing under C<refs/karr/> -- "No karr board found:", followed by
C<karr init> on its own line (L<App::karr::Error/command_hint>), the same
message C<backup>, C<destroy>, C<materialize> and C<repair> raise off
L<App::karr::BoardStore/has_board_refs> for the same state;
=item * refs present, C<refs/karr/config> missing -- a half-board: the message
names it as one, says how many task refs are at stake, and says that C<karr
init> completes it without discarding them.
=back
Call it B<after> C<sync_before>, never before: on a fresh clone the board only
exists on the remote until the pull has run, and checking first would report a
board that is merely not fetched yet as missing. The four commands that read or
clean up raw refs (C<backup>, C<destroy>, C<materialize>, C<repair>) ask
L<App::karr::BoardStore/has_board_refs> instead, so they can still deal with a
half-board left behind by an older karr.
The read-only commands do not sync, so they cannot use this method; they ask
L</require_local_board>, which puts C<karr sync> in front of C<karr init> for
exactly the fresh clone this one may assume has already been pulled.
=head2 require_local_board
$self->require_local_board; # no sync_before: reads stay offline
lib/App/karr/Role/SkillFile.pm view on Meta::CPAN
# on top of it would be the double decode App::karr::Encoding forbids). This is
# what `karr skill show` prints: the entry point, not the references behind it.
sub _skill_content {
my ($self, $name) = @_;
return $self->_skill_source_dir($name)->child('SKILL.md')->slurp_utf8;
}
# Every file one skill ships, as (relative path => characters) pairs in sorted
# path order: SKILL.md, then references/*.md. Walked from the directory rather
# than listed, so a reference file added under share/ ships without anyone
# touching this role; only *.md counts, so an editor backup next to them never
# lands in someone's .claude. The relative path is what the writers below
# rejoin to a target directory, so the layout under share/ IS the layout a
# target gets. Read with slurp_utf8 for the reason given on _skill_content.
sub _skill_files {
my ($self, $name) = @_;
my $dir = $self->_skill_source_dir($name);
my @found;
$dir->visit(
sub { my ($p) = @_; push @found, $p if $p->is_file && $p->basename =~ /\.md\z/ },
{ recurse => 1 },
misc/agent-context/.claude/agents/karr-ref-worker.md view on Meta::CPAN
---
name: karr-ref-worker
description: "App::karr Git/ref storage worker â Git::Native and CLI fallback, refs-backed BoardStore persistence, CAS, locks, sync lifecycle, encoding boundaries, backup/restore, materialize/import, repair, and helper refs. Leaves a commit-ready t...
model: inherit
tools: Read, Edit, Write, Bash, Glob, Grep
briefing:
skills:
- getty-perl-core
- getty-perl-moo
---
You are the Git/ref persistence worker for **App::karr**. You own the path from an in-memory
board operation to durable `refs/karr/*` state and remote synchronization. Apply the loaded
conventions silently.
## Territory
- `lib/App/karr/Git.pm`, `BoardStore.pm`, `Lock.pm`, `SyncGuard.pm`, and `Encoding.pm`
- `Role/BoardDiscovery.pm`, `BoardAccess.pm`, and `SyncLifecycle.pm`
- storage/transport commands: `init`, `sync`, `materialize`, `import`, `repair`, `backup`,
`restore`, `destroy`, `get-refs`, `set-refs`, and `unlock`
- skill installation plumbing in `Cmd/Skill.pm`, `Cmd/Init.pm` and `Role/SkillFile.pm`, and
the shipped skill directories `share/kanban-issues-karr-coordination/` and
`share/kanban-issues-karr-ticket/`
Preserve these invariants: canonical board state is refs-first; the file tree is only a
materialized view; concurrent writes use the established CAS/lock path; native Git handles
local operations while the CLI fallback exists for transport compatibility; characters stay
inside and octets cross only through `App::karr::Encoding`.
misc/agent-context/.claude/rules/karr-rules.md view on Meta::CPAN
- **You can spawn subagents** (orchestrating main agent): Do NOT touch behavior-relevant karr
code yourself â delegate to the domain worker below. Your lane: coordinate, inspect, plan, review diffs,
run tests, edit non-behavioral docs. Why: only the `karr-*` agents get their skills
force-loaded via `briefing.skills`; you get no briefing and would touch internals with too
little context. Specialist lanes:
| Task | Agent |
|---|---|
| Task/config semantics, lifecycle, claims, dependencies, activity log, ordinary board commands, filtering, rendering, `context`, `metrics` | `karr-board-worker` |
| Git transport, refs-backed persistence, CAS, locks, sync, encoding, `init`/`sync`/`materialize`/`import`/`repair`/`backup`/`restore`/`destroy`/`unlock`, share-file plumbing | `karr-ref-worker` |
| karr-foundation: multi-board discovery, overview, agent command resolution, drain loops, `.karr.lock`/`.karr.state`, cooldown, stall detection, auto-blocking, `disable`/`enable` | `karr-foundation-worker` |
| Behavior-relevant code that spans those domains, or none of them cleanly | `karr-worker` (generalist fallback) |
| Write/extend tests under `t/` | `karr-test-writer` |
| Commits, `Changes`, card â done, pre-release audit | `karr-release-manager` |
| Docs: POD, README, `CONTEXT.md`, ADRs, shipped skills; doc audits | `karr-doc-writer` |
Pick the narrowest domain worker that covers the task â they brief on one domain instead of
the whole distribution, and each one names the other two in its own boundaries section, so a
task that turns out to belong elsewhere gets handed back rather than solved from the wrong
context. `karr-worker` stays for work that genuinely crosses the seams.
misc/agent-context/.claude/skills/kanban-issues-karr-coordination/SKILL.md view on Meta::CPAN
the board name to a directory by that basename (from `--board NAME=PATH` or the
fleet config) â a clone parked anywhere else is a card no one can trace back.
A fresh `git clone` carries no `refs/karr/*`, but `create` pulls the board
first (it is a mutating command), so the new id continues the remote's count â
no separate `karr sync --pull`. To record the new card as
something work *here* waits on, escalate it â
[references/cross-board.md](references/cross-board.md).
## Output flags
`--json` is taken by every board command, not by `backup`, `restore`,
`destroy`, `sync`, `set-refs`, `get-refs`. `--compact` exists on exactly nine:
`board`, `config`, `context`, `dashboard`, `list`, `log`, `metrics`, `pick`,
`show` â anywhere else it is `Unknown option: compact`, exit 2.
## When you need more
| Need | Read |
|---|---|
| Every option of `create`, `show`, `move`, `edit`, `delete`, `archive`; dependency rules | [references/cards.md](references/cards.md) |
| `list` filters and sorting, `board`, `dashboard`, `log`, `metrics`, `context --write-to` | [references/queries.md](references/queries.md) |
| `pick` ordering, `handoff` options, `unlock` for stale locks, timeouts, several agents on one board | [references/claims.md](references/claims.md) |
| A card waits on another repository: `--needs BOARD#ID`, `--escalated-from`, `karr needs --resolve` | [references/cross-board.md](references/cross-board.md) |
| `config get/set`, writable keys, the config YAML, `disable`/`enable` for karr-foundation | [references/config.md](references/config.md) |
| `sync`, fresh clones, stored card format, `materialize`/`import`, `repair`, `backup`/`restore`/`destroy`, `set-refs`/`get-refs` | [references/storage.md](references/storage.md) |
| `init`, `skill install/check/update`, `completion`, Docker | [references/setup.md](references/setup.md) |
misc/agent-context/.claude/skills/kanban-issues-karr-coordination/references/storage.md view on Meta::CPAN
karr repair # report what would change
karr repair --yes # migrate
```
Boards written by karr 0.402 or earlier stored UTF-8 double-encoded; they are
repaired on read meanwhile, and this migrates the refs once. It also raises a
`started` stamp written as a bare date (before k68) up to the card's own
`created` â the dry run says how many cards. `completed` stamps with the same
problem are reported, not touched.
## backup / restore / destroy
```bash
karr backup > karr-backup.yml
karr backup --output karr-backup.yml
karr restore --yes < karr-backup.yml # replaces the whole refs/karr/* namespace
karr restore --yes --input karr-backup.yml
karr destroy --yes # deletes refs/karr/* here AND on the remote
```
`restore` and `destroy` are destructive; take a `backup` first.
## Helper refs
```bash
karr set-refs superpowers/spec/1234.md draft ready # arguments joined with one space: a one-line payload
karr set-refs superpowers/spec/1234.md < design.md # no content argument: stdin, stored verbatim
karr get-refs superpowers/spec/1234.md > design.md # back unchanged
```
Shared payloads in Git refs outside the protected namespaces (`refs/karr/*`,
misc/agent-context/.claude/skills/karr-single-binary/references/pp-recipe.md view on Meta::CPAN
## 3. Verify
```bash
PAR_GLOBAL_TEMP="$(mktemp -d)" ./karr --help # fresh cache, first-run extract
# then exercise EVERY subcommand against a throwaway board (trap 1 dies at runtime)
```
Exercise the subcommands in a **separate `mktemp -d` + `git init` repo**, never in
the karr checkout â a worktree shares `refs/karr/*` with the real board, so a
verification `create`/`move`/`destroy` there mutates live state. `karr <cmd> --help`
for each of the 32 commands is the cheap trap-1 probe (forces the class to load,
no side effects); pair it with one real initâcreateâlistâmoveâhandoffâbackupâ
restoreâdestroy flow to prove libgit2/FFI end-to-end.
Also run `karr skill install --agent claude-code` in a fresh `mktemp -d` project
and byte-compare what it wrote against the checkout's own `share/*/SKILL.md`
(and `references/*.md`) â the missing-`share/` `-a` trap above is invisible to
every check so far, since nothing above it reads the skill files, only loads
the class. `scripts/verify-binary.sh`'s trap 3 is exactly this install-and-diff.
Finally `scripts/check-binary-libs.sh ./karr`: none of the runs above can see a
lib the target lacks, because they run where it is installed. This one reads
misc/agent-context/CLAUDE.md view on Meta::CPAN
Engineering discipline, the delegation lane, board coordination, and the release policy live in
`.claude/rules/karr-rules.md` â auto-loaded by Claude Code at launch. Don't restate them here.
**Delegate behavior-relevant code instead of editing it yourself** (the rule and rationale are in
the rules file). Agents in this repo (skills force-loaded via `briefing.skills`):
| Task | Agent |
|---|---|
| Task/config semantics, lifecycle, claims, dependencies (`needs`/`CrossBoard`), activity log, ordinary board commands, filtering, rendering | `karr-board-worker` |
| Git transport, refs-backed storage, CAS, locks, sync, encoding, materialize/import/backup/restore | `karr-ref-worker` |
| karr-foundation: discovery, drain loops, per-repo lock/state, cooldown, auto-blocking, `disable`/`enable` | `karr-foundation-worker` |
| Behavior-relevant code spanning those domains, or none of them cleanly | `karr-worker` (generalist fallback) |
| Write/extend tests under `t/` | `karr-test-writer` |
| Commits, `Changes`, card â done, pre-release audit | `karr-release-manager` |
| Docs: POD (`=attr`/`=method`, `# ABSTRACT`), README, `CONTEXT.md`, ADRs, shipped skills; doc audits | `karr-doc-writer` |
Take the narrowest domain worker that fits; each names the other two in its boundaries section
and hands a misrouted task back rather than solving it from the wrong context.
**Dogfood:** karr tracks its own work on its own board (`refs/karr/*`). Use `karr list --compact`
misc/agent-context/CLAUDE.md view on Meta::CPAN
| `metrics` | implemented | `metrics` |
| `log` | implemented | `log` |
| `config` | implemented | `config` |
| `context` | implemented | `context` |
| `agent-name` | implemented | `agent-name` |
| `skill` | implemented | `skill` |
| `materialize` | implemented | â (refsâfiles bridge) |
| `import` | implemented | â (filesârefs bridge) |
| `repair` | implemented | â (migrates a 0.402-or-earlier board off double-encoded UTF-8) |
| `sync` | implemented | â (explicit refs pull/push) |
| `backup` | implemented | â (board snapshot to YAML) |
| `restore` | implemented | â (snapshotârefs, destructive) |
| `destroy` | implemented | â (remove `refs/karr/*` incl. remote) |
| `set-refs` / `get-refs` | implemented | â (helper refs outside the board) |
| `disable` / `enable` | implemented | â (board-level opt-out from karr-foundation runs) |
## Key design decisions
- **MooX::Cmd** for subcommand dispatch (not App::Cmd â lighter, Moo-native)
- **MooX::Options** for CLI option parsing
- **YAML::XS** for frontmatter (fast, correct YAML parsing)
scripts/verify-binary.sh view on Meta::CPAN
set -euo pipefail
BIN=$(realpath "${1:?usage: verify-binary.sh <karr-binary>}")
export PAR_GLOBAL_TEMP="$(mktemp -d)"
"$BIN" --version
"$BIN" --help >/dev/null
# Trap 1: force every dynamically-loaded Cmd class to load (no side effects).
for cmd in init create list show move edit delete board dashboard pick unlock \
archive handoff needs metrics log config context agent-name skill \
materialize import repair sync backup restore destroy \
set-refs get-refs disable enable completion; do
"$BIN" "$cmd" --help >/dev/null || { echo "FAIL: subcommand $cmd" >&2; exit 1; }
done
echo "trap1 (subcommand classes): OK"
# Trap 2: a real libgit2/FFI round trip in a throwaway repo, never the checkout.
work=$(mktemp -d)
(
cd "$work" && git init -q .
"$BIN" init
"$BIN" create "smoke test card" >/dev/null
"$BIN" list --compact
id=$("$BIN" list --compact | awk 'NR==1{gsub(/#/,"",$1); print $1}')
"$BIN" move "$id" in-progress --claim smoke
"$BIN" handoff "$id" --claim smoke --note ok
"$BIN" backup > board.yaml && test -s board.yaml
"$BIN" restore --yes --input board.yaml
"$BIN" list --compact
"$BIN" destroy --yes
)
echo "trap2 (libgit2 board flow): OK"
# Trap 3: karr's own share/, which the binary has only if build-binary.sh packed
# it. Nothing above reads it -- `skill --help` loads the class, not the files --
# so a binary without it passes traps 1 and 2 and dies the first time someone
# runs `karr skill` or `karr init --claude-skill` (k308). Every skill under the