/ 
App-karr-0.102
River stage zero No dependents
/ App::karr

NAME

App::karr - Kanban Assignment & Responsibility Registry

VERSION

version 0.102

SYNOPSIS

karr init --name "My Project"
karr create "Fix login bug" --priority high
karr list --status todo,in-progress
karr board
karr set-refs superpowers/spec/1234.md draft ready
karr get-refs superpowers/spec/1234.md

DESCRIPTION

App::karr is the central module behind the karr command line client. The distribution manages a Git-native kanban board stored in refs/karr/*, where task cards are Markdown payloads and board configuration is sparse YAML kept in refs rather than in checked-in work tree files.

The distribution is intended for repositories that want Git to remain the transport and source of truth. Commands materialize a temporary board view only for the lifetime of a command, then serialize changes back into refs and push them onward. This keeps the repository free of a persistent karr/ board tree and avoids ordinary file-level merge conflicts for shared task state.

This module gives the architectural overview. If you want day-to-day command usage, command groups, and command-by-command navigation, start with karr.

ARCHITECTURE

  • refs/karr/config

    Sparse board configuration overrides layered onto code defaults from App::karr::Config.

  • refs/karr/meta/next-id

    Dedicated metadata ref for numeric id allocation.

  • refs/karr/tasks/*/data

    Task payloads stored in the same Markdown plus YAML frontmatter shape used by App::karr::Task.

  • refs/karr/log/*

    Append-style activity log entries written as per-agent JSON lines.

App::karr::Git provides the low-level Git ref operations, while App::karr::BoardStore handles the higher-level board model: merged config, task loading, materialization, serialization, snapshots, and restore.

CLI ENTRY POINT

The installed executable is karr. Running karr without a subcommand shows the board summary by default, and the command-specific modules under App::karr::Cmd::* implement the individual operations.

Use karr when you want to learn:

  • which command to run for a task

  • how backup, restore, destroy, and helper refs fit together

  • which module implements each subcommand

  • how to use the Docker-wrapped CLI day to day

DOCKER RUNTIME

Perl installation remains the normal development path, but Docker is a first-class runtime option for vendoring karr into other repositories or tooling environments.

The default raudssus/karr:latest image starts as root only long enough to inspect the mounted /work directory and then drops to the matching numeric uid and gid before running karr. This prevents root-owned project files when the image is used through a shell alias. The companion raudssus/karr:user image is the fixed-user variant for environments that prefer a predictable non-root runtime without that auto-adjustment.

See karr and README.md for the shell alias form and operator-focused examples.

PROGRAMMATIC USAGE

Although the distribution is centered on the CLI, the lower-level modules are usable from Perl when you want to inspect or manipulate board refs directly.

Reading the current board state:

use App::karr::Git;
use App::karr::BoardStore;

my $git = App::karr::Git->new(dir => '.');
my $store = App::karr::BoardStore->new(git => $git);

my $config = $store->load_config;
my @tasks  = $store->load_tasks;

Creating a task and writing it back:

use App::karr::Task;

my $id = $store->allocate_next_id;
my $task = App::karr::Task->new(
  id       => $id,
  title    => 'Document the release process',
  status   => 'backlog',
  priority => 'high',
);

$store->save_task($task);
$git->push;

Taking a full board snapshot for export logic:

my $snapshot = $store->snapshot;

These modules are more appropriate for Perl automation than instantiating App::karr itself, which mainly exists as the MooX::Cmd dispatcher for the CLI.

BOARD DISCOVERY

Most commands automatically search upward from the current directory for a Git repository that contains refs/karr/*. The global --dir option overrides the starting directory used for that repository discovery.

DEFAULT BEHAVIOUR

Running karr without a subcommand shows the board summary, which makes the tool convenient as a quick project status command.

SEE ALSO

karr, App::karr::Git, App::karr::BoardStore, App::karr::Task, App::karr::Config, App::karr::Cmd::Init, App::karr::Cmd::Skill

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-app-karr/issues.

IRC

Join #ai on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.