view release on metacpan or  search on metacpan

docs/superpowers/specs/2026-03-22-ref-first-board-design.md  view on Meta::CPAN

  mutating commands

It should not create `karr/` in the working tree.

### Read commands

Commands such as `list`, `show`, `board`, `context`, and `config` should read
directly from refs after a fetch/materialize step that exists only in memory or
in a temporary directory.

### Write commands

Commands such as `create`, `edit`, `move`, `archive`, `delete`, `pick`,
`handoff`, and `config set` should follow this sequence:

1. fetch current refs
2. load canonical state from refs
3. apply the requested mutation
4. write only the affected refs
5. push updated refs

There should be no persistent repo-local board cache.

## Temporary materialization

The pragmatic implementation path is to keep task/config parsing formats but
move any file materialization into a temp area created per command execution.

That gives us:

- minimal parser churn
- 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.

## Migration

Boards created under the current local-file-first model need a migration path.
The tool should support one of these:

- detect a legacy `karr/` directory and import it once into refs
- provide an explicit migration command

The safe default is explicit migration, because silent import can hide bad
state.

## Risks

- many commands currently assume `board_dir`, `tasks_dir`, and `config.yml`
- tests are heavily built around a local directory
- `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