view release on metacpan or  search on metacpan

.claude/rules/karr-rules.md  view on Meta::CPAN

# App::karr House Rules

Apply to every task in this repository unless explicitly overridden. Bias: caution over speed
on non-trivial work; use judgment on trivial tasks. Loaded automatically by Claude Code at
launch (same priority as `.claude/CLAUDE.md`). Subagents get their discipline from the skills
force-loaded via `briefing.skills` — this file is for the orchestrating agent.

## Engineering discipline

1. **Think before coding** — State assumptions. When uncertain, ask rather than guess. Present
   alternatives when ambiguous. Push back when a simpler approach exists. Stop when confused;
   name what's unclear.
2. **Simplicity first** — Minimum code that solves the problem. Nothing speculative. No
   abstractions for single-use code.
3. **Surgical changes** — Touch only what you must. Don't "improve" adjacent code, comments, or
   formatting. Match existing style.
4. **Read before you write** — Before new code, read exports, immediate callers, shared
   utilities (`Role/*`, `BoardStore`, `Git`, `Task`, `Config`). "Looks orthogonal" is dangerous.
5. **Tests verify intent, not just behavior** — A test that can't fail when the logic changes is
   wrong. Reproduce a bug before fixing it; leave a regression test behind.
6. **Match the codebase's conventions, even if you disagree** — Conformance > taste. Surface a
   harmful convention; don't fork silently.
7. **Fail loud** — "Done" is wrong if anything was skipped silently. "Tests pass" is wrong if any
   were skipped. Surface uncertainty, don't hide it.

## Delegation

Depends on whether the Agent/Task tool is available to you.

- **You can spawn subagents** (orchestrating main agent): Do NOT touch behavior-relevant karr
  code yourself — delegate to the domain worker below. Your lane: coordinate, inspect, plan, review diffs,
  run tests, manage git, edit non-behavioral docs. Why: only the `karr-*` agents get their skills
  force-loaded via `briefing.skills`; you get no briefing and would touch internals with too
  little context. Specialist lanes:

  | Task | Agent |
  |---|---|
  | Task/config semantics, lifecycle, claims, dependencies, activity log, ordinary board commands, filtering, rendering, `context`, `metrics` | `karr-board-worker` |
  | Git transport, refs-backed persistence, CAS, locks, sync, encoding, `init`/`sync`/`materialize`/`import`/`repair`/`backup`/`restore`/`destroy`/`unlock`, share-file plumbing | `karr-ref-worker` |
  | karr-foundation: multi-board discovery, overview, agent command resolution, drain loops, `.karr.lock`/`.karr.state`, cooldown, stall detection, auto-blocking, `disable`/`enable` | `karr-foundation-worker` |
  | Behavior-relevant code that spans those domains, or none of them cleanly | `karr-worker` (generalist fallback) |
  | Write/extend tests under `t/` | `karr-test-writer` |
  | Pre-release audit (Changes, cpanfile, dist.ini, version) | `karr-release-checker` |
  | POD (`=attr`/`=method`, ABSTRACT) | `karr-pod-writer` |

  Pick the narrowest domain worker that covers the task — they brief on one domain instead of
  the whole distribution, and each one names the other two in its own boundaries section, so a
  task that turns out to belong elsewhere gets handed back rather than solved from the wrong
  context. `karr-worker` stays for work that genuinely crosses the seams.

- **You cannot spawn subagents** (you ARE a `karr-*` agent): The delegation lock does not apply —
  implement, refactor, debug, and test per these rules.

Behavior-relevant = CLI command logic (`Cmd/*`), refs-backed storage (`BoardStore`, `Git`,
`Lock`, `SyncGuard`), `Task`/`Config` parsing and writing, sync lifecycle, tests.

## Coordination — karr board (dogfood, always in scope)

This repo manages its own work on its own board — `refs/karr/*` already exists here. karr is the
tool *and* the workflow, so use it; don't invoke a skill first, just run it:

- `karr list --compact` / `karr board` — open work · `karr show ID` — detail
- `karr create "Title" --priority high --tags a,b --body '…'` — new ticket
- `karr edit ID -a "note"` · `--claim NAME` · `--block "why"` — update
- `karr move ID in-progress --claim NAME` — start · `karr handoff ID --claim NAME --note "…"` — to review

Bugs found while dogfooding become tickets on this board. Full command surface (pick / context /
set-refs / multi-agent): skill `kanban-issues-karr-cli`.

## Release — never without permission