---
name: kata-harness-setup
description: Set up the kata roll in a project that already runs (or is starting) the bring loop — confirm bring/ exists, explain where the roll's own ledger lives, walk through the opt-in timer, and make the two-plugin coexistence with bring-loop explicit. Use when the user says "set up kata-harness", "install the roll plugin", "add rolls on top of bring-loop", or asks how the timed roll relates to their daily bring.
model: inherit
category: govern-publish
---

# Kata-harness-setup — install the roll runner alongside bring-loop

A roll never runs on its own queue — it ticks over the **same** `bring/`
queue bring-loop already reads. Setup here is mostly about making sure that
foundation exists, then explaining the one new file and the one new plugin
surface layered on top of it.

## 1. Make sure the bring queue exists

Check for `bring/actions.md` in the project root.

- **Missing:** scaffold it with bring-loop itself — the queue format has one
  owner, and it is not this plugin. Invoke the bring-loop plugin's
  `bring-setup` skill: its `bring_core.py init` creates `bring/actions.md`
  and `bring/ledger.jsonl`, never overwriting anything that already exists.
  If bring-loop isn't installed yet, install it first
  (`/plugin install bring-loop@dojo-genesis` — the same marketplace this
  plugin ships from). kata-harness deliberately ships no second init: its
  `scripts/` holds only `roll_core.py`, whose roll verbs assume the queue
  already exists.
- **Present:** leave it alone. If bring-loop is already installed and in use,
  there is nothing to scaffold — the roll rides on the existing queue as-is.

If the queue is genuinely empty (a fresh init, or an existing one with
nothing in it), this is the moment to seed 2-3 real outward actions — ask the
user what they're sitting on, the same question bring-setup asks. A roll over
an empty queue has nothing to surface.

## 2. Where the roll's own ledger lives

Nothing to create by hand — the first `roll-start` call creates
`bring/roll-ledger.jsonl` on its own, the same way logging a bring creates
`bring/ledger.jsonl` on its own. Explain the shape of the file split, since
it's the one thing genuinely new here:

| File | Owner | Concern |
|---|---|---|
| `bring/actions.md` | human + agent (unchanged) | the queue — the roll never writes here |
| `bring/ledger.jsonl` | bring-loop, append-only | outcome content — `sent`/`decided`/`closed`/`shipped`/`skipped`, shared by both plugins |
| `bring/roll-ledger.jsonl` | kata-harness, append-only | session shape — ticks, targets, cadence, pauses; a bookkeeping axis of its own, never blended into the outcome streams |
| `bring/ROLL-STATUS.md` | kata-harness, generated | the current-roll face — regenerate with `roll-status`, never hand-edit |

## 3. The opt-in timer

**Model/self-paced by default** — no clock, no daemon, just tick when you're
ready.

- `--timer` on `roll-start` turns on an in-session display only: count-up if
  no duration is set, count-down if a cadence (e.g. `--cadence 25m`) is set.
- Say plainly that this is a **display, not a process** — it starts no clock
  that outlives the session, and expiry never resolves, skips, or advances a
  tick by itself. That stays true whether `--timer` is on or off.

## 4. Coexistence with bring-loop — say this explicitly

- **Distinct everything, on purpose:** plugin `kata-harness` (not `bring`),
  skills `kata-harness` / `kata-harness-setup` (not `bring` / `bring-setup`),
  ledger `bring/roll-ledger.jsonl` (not `ledger.jsonl`). Installing this
  plugin never touches bring-loop's own files, hooks, or skills.
- **Both keep running, unnagged by each other:** bring-loop's SessionStart
  brief and Stop nudge fire every session, same as always. This plugin's own
  SessionStart hook stays silent unless a roll is actually open right now —
  it is a status report, not a second daily nag.
- **One outcome ledger, shared honestly:** resolving a tick with
  `roll-resolve` writes to the *same* `bring/ledger.jsonl` bring-loop reads —
  a roll-produced `sent` counts toward the week's streams and the streak
  exactly like any other logged action. The roll adds a session on top; it
  does not fork the scoring.
- **One queue, never duplicated:** starting a roll does not copy or fork
  `bring/actions.md`. It ticks over the same open queue, minus whatever it
  has already surfaced this session.

## 5. Show them the shape

Walk through one real cycle so they see it end to end:
`roll-start --reps 3` (or `--minutes N`) -> `roll-tick` (one bring, staged)
-> their word -> `roll-resolve` / `roll-skip` / `roll-elapse` -> `roll-tick`
again -> ... -> `completed`. Two sentences of contract: the roll surfaces and
stages one rep per tick inside a bounded session; you execute, and rolling
forward an unworked tick is not a failure — the roll remembers.

## 6. Optional wiring (their call)

`roll-check` gates `ROLL-STATUS.md` freshness and a handful of conformance
assertions (see `SPEC.md`'s conformance gate section) — worth wiring into CI
only if they ask. Cadence itself is host-supplied: a manual `roll-tick` per
message, or their own `/loop` pointed at it — this plugin stays
timer-agnostic and never assumes a driver. Do not wire anything beyond this
project without being asked.