kata-harness-setup

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.