This file provides project guidance for Claude Code and similar coding agents.
App::karr — Kanban Assignment & Responsibility Registry
A Perl reimplementation of kanban-md, a file-based kanban board designed for multi-agent workflows. The reference implementation is in Go and is not part of this workspace.
This is a Dist::Zilla distribution using [@Author::GETTY].
Engineering discipline, the delegation lock, board coordination and the publish gate are shared
house rules (skilletor bundle getty-cpan-dist@getty); the lanes, the dogfood board and the
release specifics live in .claude/rules/karr-rules.md — all 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 shared rule agent-delegation). 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
/ karr board for open work and file bugs found here as tickets. Full surface: skill
kanban-issues-karr-coordination.
The Go implementation is the feature reference for the board commands. It is not
checked out here — clone it to ../kanban-md/ when you need to compare
behaviour, then read README.md (command reference and design principles),
cmd/ (CLI commands), internal/task/ (file parsing, validation, consistency),
internal/board/ (filtering, sorting, picking) and internal/config/ (schema,
migration, defaults).
Goal: Feature parity with kanban-md for the board itself, but idiomatic Perl
with Moo, MooX::Cmd, MooX::Options. What karr has beyond it — refs-first
storage, cross-board dependencies, karr-foundation — has no kanban-md
counterpart and no parity obligation.
bin/karr— CLI entry pointlib/App/karr.pm— Main app, MooX::Cmd rootlib/App/karr/Cmd/*.pm— Subcommands (MooX::Cmd default namespace)lib/App/karr/Role/Output.pm— Role for the --json output option and the JSON printerslib/App/karr/Role/CompactOutput.pm— Role for --compact, composed only by the nine commands that render onelib/App/karr/Encoding.pm— The character/octet boundary: argv, std handles, ref blobs, YAML, JSONlib/App/karr/Role/BoardDiscovery.pm— Role providing git/store/config discoverylib/App/karr/Role/SyncLifecycle.pm— Role providing sync_before/sync_after with retrylib/App/karr/Role/BoardAccess.pm— Composes BoardDiscovery + SyncLifecycle + task accesslib/App/karr/Task.pm— Task object: parse/write Markdown+YAML frontmatterlib/App/karr/Config.pm— Board config management (defaults + helpers)lib/App/karr/SyncGuard.pm— Push insurance on die/croaklib/App/karr/Git.pm— Low-level Git operations; local ops native via Git::Native (libgit2), with a git-CLI fallback for remote transport (ssh-config/ProxyCommand)lib/App/karr/BoardStore.pm— Ref-backed board storage (load_tasks, save_task, effective_config)lib/App/karr/Lock.pm— Advisory task locking via refslib/App/karr/ActivityLog.pm— Activity log writer; role-qualified identities underrefs/karr/log/*lib/App/karr/CrossBoard.pm— Cross-board dependencies: a link from a card here to a card on another board (BOARD#ID)lib/App/karr/Error.pm— Turns internal errors into one clean user-facing linelib/App/karr/Home.pm— The user's home directory (HOME, on Windows alsoUSERPROFILE); nothing else reads$ENV{HOME}
bin/karr-foundation drives agent runs across several boards; App::karr::Foundation
is the single-shot daemon, and the subsystem beside it splits as follows:
Foundation/Overview.pm— read-only multi-board status dashboardFoundation/Picker.pm— ticket selection: the one card a ticket-mode run is aboutFoundation/Runner.pm— command execution: fork/pipe/select tee plus run classificationFoundation/Agents.pm— agent definitions, invocation contract, per-agent availabilityFoundation/State.pm— per-repo state: lock file, JSON state, cooldown backoffFoundation/Limits.pm— concurrency limits: machine ceiling, per-agent estimates, chain headerFoundation/ChainStore.pm— chain and run-log storage underrefs/karr-foundation/*Foundation/Executor.pm— chain executor: picks a ready step, runs it, writes its state backFoundation/Questions.pm— question mailbox underrefs/karr-foundation/questions/*
Canonical state lives in refs/karr/*. The tasks/ directory (with its
config.yml) is a materialized view, not the source of truth, and is always in
F<.gitignore> — never committed. karr materialize writes that file view from
the refs (BoardStore->materialize_to) and karr import --yes reads it back in
(serialize_from) — a bridge for kanban-md interop and grepping files, not a
storage backend.
| Command | Status | kanban-md equivalent |
|---|---|---|
init |
implemented | init |
create |
implemented | create / add |
list |
implemented | list / ls |
show |
implemented | show |
move |
implemented | move |
edit |
implemented | edit |
delete |
implemented | delete / rm |
board |
implemented | board / summary |
dashboard |
implemented | — (configuration-free multi-board overview under a directory) |
pick |
implemented | pick |
unlock |
implemented | — (show and break pick locks) |
archive |
implemented | archive |
handoff |
implemented | handoff |
needs |
implemented | — (report/resolve cross-board dependencies) |
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) |
- 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)
- Path::Tiny for all file operations
- No namespace::clean in command classes (incompatible with MooX::Options)
- Task file format 100% compatible with kanban-md (interop goal)
- Characters inside, octets only at the edges. Everything between the CLI
entry point and the Git ref blob is a Perl character string.
App::karr::Encodingowns every crossing —@ARGV, STDOUT/STDERR, ref read/write, YAML, JSON — and nothing else mayEncode::encode/decode, callYAML::XS::Dump/Load, orencode_json/decode_jsondirectly.Path::Tiny'sslurp_utf8/spew_utf8are already character-level: putting an encode in front of one is a double encode. Boards written before this rule are detected viarefs/karr/meta/encodingand repaired on read;karr repairmigrates them.
prove -l t/ # Run all tests
prove -l t/01-task.t # Run specific test
dzil test # Full Dist::Zilla test
dzil build # Build distributionOpen work lives on the karr board (refs/karr/*) — karr list --compact or
karr board. This file deliberately keeps no second copy of it: the summary that
used to stand here dated from the initial commit, was never reconciled with the
board, and by the time anyone noticed, none of its five items existed as a
ticket while it claimed the board held the live status.
- Keep runtime dependencies in
cpanfile, notdist.ini - For user-visible changes, add an unreleased entry under
{{$NEXT}}inChanges - POD follows
[@Author::GETTY]conventions (inline=attr,=method, no manual NAME/VERSION/AUTHOR sections) # ABSTRACT:comment required on every .pm file- Release policy (
dzil releaseonly with explicit go-ahead) is in the shared rulepublish-gate
Agent/skill/rule material lives under .claude/:
rules/karr-rules.md— project house rules, auto-loaded (lanes, dogfood board, release); the shared ones arrive asrules/.local.*.mdfrom skilletoragents/karr-*.md— the project agent fleet (briefing-aware; skills force-loaded at spawn)skills/— thirteen skills. Six are owned here:kanban-issues-karr-coordinationandkanban-issues-karr-ticket(other repos install these from skilletor sourcekarr), pluskarr-core,karr-foundation-cli,karr-single-binaryandperl-file-sharedir. Seven are installed by skilletor from.claude/skilletor.jsonand not tracked: five listed there (getty-git-commit-style,getty-git-usage,getty-perl-core,getty-perl-moo,perl-release-dist-ini) and two that come with thegetty-cpan-distbundle (getty-perl-pod,getty-perl-release-author-getty); they change in their source. Keep the skill names stable.kanban-issues-karr-coordinationandkanban-issues-karr-ticketare each hardlinked file-for-file to their directory undershare/(share/kanban-issues-karr-coordination/,share/kanban-issues-karr-ticket/— whatkarr skill installships:SKILL.mdplusreferences/*.md), so editing one edits the other. Edit them with a shell redirect (cat > .claude/skills/<skill>/SKILL.md), which keeps the shared inode. A new file under either directory has to be linked into the other by hand:ln <canonical> <other>(t/62).
Two more documents carry decisions rather than instructions:
CONTEXT.md— the domain vocabulary (Claim vs. Assignee vs. Lock, Activity log, …), including the words to avoid. Read it before naming anything new.docs/adr/— architecture decision records: refs-first storage, the exit-code contract, role-qualified log identity, foundation as a coordinator, board-level disable. Read the relevant one before changing the shape it describes.
Keep this file focused on the repository; behavioral rules belong in rules/, not here.