view release on metacpan or  search on metacpan

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

}
```

### Embed board state in AGENTS.md or CLAUDE.md

```bash
karr context --write-to CLAUDE.md
# Inserts/updates between <!-- BEGIN kanban-md context --> sentinels
# Agent sees current board state at session start automatically
```

### Agent identity strategies

| Strategy | Persistence | Use case |
|----------|------------|----------|
| `karr agentname` | Ephemeral (new each call) | One-shot tasks |
| `git config user.email` | Stable per machine | Persistent agents |
| `$HOSTNAME-$PID` | Stable per process | Docker containers |
| Fixed name in hook/config | Stable always | Dedicated agent role |

**Recommendation for persistent agents:** Use git identity or a fixed name, not `karr agentname`.

### Key flags for agent consumption

| Flag | Purpose |
|------|---------|
| `--json` | Machine-readable output on ALL commands |
| `--compact` | One-line output (good for log context) |
| `--claimed-by NAME` | Filter to "my" tasks |
| `--status S1,S2` | Filter by status |
| `--tags t1,t2` | Specialize agents by domain |

### Docker + Git sync

```bash
# Mount git config for identity:
docker run --rm -v $(pwd):/work \
  -v $HOME/.gitconfig:/root/.gitconfig:ro \
  -v $HOME/.ssh:/root/.ssh:ro \
  raudssus/karr sync
```

## Test Coverage Requirements

The ref-based sync is the highest-risk change. Required tests:

1. **`write_ref`/`read_ref` roundtrip** — verify commit-wrapped refs can be written and read back
2. **`push`/`fetch` with commit-wrapped refs** — verify refs actually transfer between repos (test with `git clone --bare` + two working copies)
3. **Materialize/serialize roundtrip** — create task via file, serialize to ref, delete file, materialize from ref, verify content matches
4. **Pick with Lock** — two sequential picks should claim different tasks
5. **Log append + read** — append entries from two "agents", verify merged output is sorted
6. **`from_string`/`from_file` parity** — same content parsed both ways produces identical Task objects
7. **`is_repo` from subdirectory** — verify detection works from `karr/` inside a git repo
8. **Config sync** — `next_id` collision prevention across two agents

Existing tests (`t/01-task.t` through `t/07-context.t`) must continue to pass unchanged.

## Out of Scope (v0.005+)

- `metrics` command (throughput, cycle time)
- `sync --watch` (background daemon polling)
- Dependency checking (block tasks with unsatisfied deps)
- Self-healing IDs
- WIP limit enforcement on move
- TUI (Tickit)
- External repo refs (`refs/karr/external/`)
- Messages in task metadata