view release on metacpan or  search on metacpan

docs/superpowers/specs/2026-03-19-v0004-release-design.md  view on Meta::CPAN

```

**Command:** `karr log [--agent NAME] [--task ID] [--last N] [--json]`

Reads all `refs/karr/log/*` refs, merges entries, sorts by `ts`, applies filters. Default: last 20 entries.

### 9. Docker: Git identity fallback

**File:** `Dockerfile`

```dockerfile
ENV GIT_AUTHOR_NAME="karr"
ENV GIT_AUTHOR_EMAIL="karr@localhost"
ENV GIT_COMMITTER_NAME="karr"
ENV GIT_COMMITTER_EMAIL="karr@localhost"
```

Overridable via `-e` flags on `docker run`.

### 10. Fix: Changes file — remove "experimental"

Replace "experimental" with stable language. Git sync via refs/karr/* is a core feature.

## AI Agent Integration Scenarios

### Scenario 1: Claude Code Session — Solo Agent

One agent, one repo. The simplest case.

```bash
# Setup (once)
docker run --rm -v $(pwd):/work raudssus/karr init --name "my-project"
docker run --rm -v $(pwd):/work raudssus/karr skill install

# Agent session starts, skill is loaded automatically
# Agent checks what's available:
karr pick --claim $(karr agentname) --status todo --move in-progress --json

# Agent works on the task...

# Agent hands off:
karr handoff 5 --claim swift-fox --note "Implemented auth module, tests pass" -t

# Agent marks done:
karr move 5 done --claim swift-fox
```

**Integration hint:** Add a Claude Code hook that runs `karr context --write-to AGENTS.md` on session start, so the agent always sees the current board state.

### Scenario 2: Multiple Claude Code Instances — Parallel Agents

Three agents on the same repo, each in a separate terminal/worktree.

```bash
# Agent A picks first available task:
karr pick --claim agent-a --move in-progress --json
# → picks task 3 (highest priority unclaimed)

# Agent B picks next available (task 3 is now claimed):
karr pick --claim agent-b --move in-progress --json
# → picks task 7 (next highest, task 3 locked by agent-a)

# Agent C picks:
karr pick --claim agent-c --move in-progress --json
# → picks task 12

# Agent A finishes, hands off:
karr handoff 3 --claim agent-a --note "done" -t
# Sync pushes → agents B and C see updated board on next sync

# Agent B checks what's blocked:
karr list --status review --json
```

**Integration hint:** Use `karr pick --claim $NAME --tags backend` to let agents specialize by domain. Tag tasks with `backend`, `frontend`, `docs` etc.

### Scenario 3: Cross-Repo Agent Coordination

Human manages GitHub Issues. Bridge agent transfers selected issues to karr. Worker agents pick and execute.

```
GitHub Issues                    karr board                    Agent work
┌──────────────┐   bridge    ┌──────────────────┐  pick    ┌──────────────┐
│ Issue #42    │ ──agent──→  │ Task 1 (backlog) │ ──────→  │ Agent works  │
│ Issue #43    │ ──agent──→  │ Task 2 (backlog) │          │ on task 1    │
│ Issue #44    │             │ Task 3 (todo)    │          │              │
└──────────────┘             └──────────────────┘          └──────────────┘
```

```bash
# Bridge agent (runs periodically or via hook):
ISSUES=$(gh issue list --repo owner/repo --label agent-ready --json number,title)
# For each issue:
karr create "$TITLE" --priority high --body "See: owner/repo#42" --tags github

# Worker agent:
karr pick --claim worker-1 --move in-progress --json
# Agent reads task body, sees "See: owner/repo#42"
# Agent works on the issue, creates PR
# Agent hands off:
karr handoff 1 --claim worker-1 --note "PR #99 created" -t
```

**Integration hint:** The bridge is NOT part of karr — it's a simple script or Claude Code hook. karr stays source-agnostic. The task body carries the link back to the original issue.

### Scenario 4: Continuous Agent Loop with Docker

A persistent agent container that polls for work, executes, and reports.

```bash
#!/bin/bash
# agent-loop.sh — runs inside Docker or as a cron job
NAME="docker-agent-$(hostname)"

while true; do
    # Sync first
    karr sync --pull

    # Try to pick a task
    TASK=$(karr pick --claim "$NAME" --status todo --move in-progress --json 2>/dev/null)

    if [ -z "$TASK" ]; then
        sleep 30
        continue
    fi

    TASK_ID=$(echo "$TASK" | jq -r '.id')
    TASK_TITLE=$(echo "$TASK" | jq -r '.title')

    echo "Working on task $TASK_ID: $TASK_TITLE"