Refresh RTK integration: migrate to rtk hook claude + ship Python worktree.yaml

overlays/hiskens/RTK-INTEGRATION.md

@@ -0,0 +1,83 @@
+# RTK Integration — Hiskens Overlay
+
+This document captures how the Hiskens overlay hooks into [RTK (Rust Token
+Killer)](https://github.com/rtk-ai/rtk), a CLI proxy that compresses common
+developer-tool output before it reaches the LLM. Readers should skim
+MAINTENANCE.md first for the overlay sync workflow.
+
+## Why RTK
+
+RTK reduces token usage by 60–90% on commands the LLM runs frequently
+(`git diff`, `grep`, `ls`, `ruff`, `pytest`, ...). For science projects
+running multi-agent pipelines, the ruff/pytest output compression alone
+saves significant context per check loop. Install via `rtk init -g`;
+verify with `rtk --version` and `rtk gain`.
+
+## Hook wiring — API migration history
+
+Two generations exist. The overlay currently ships the second.
+
+| Era | Hook command | Status |
+|---|---|---|
+| Legacy | `$HOME/.claude/hooks/rtk-rewrite.sh` (shell wrapper that invoked `rtk rewrite`) | Removed in rtk 0.37.x — script no longer installed |
+| Current | `rtk hook claude` (direct binary, reads PreToolUse JSON from stdin) | In use as of overlay v1.x |
+
+The migration to `rtk hook claude` happened because the wrapper script was
+no longer bundled with rtk binaries, causing PreToolUse hooks to fail
+silently (measured at 0.2% RTK coverage across 12357 subagent Bash calls
+via `rtk discover`). See commit history of
+`overlays/hiskens/templates/claude/` for the rollout.
+
+**If you ever reintroduce a wrapper script**: mirror the update across all
+8 agent frontmatters (check/plan/debug/research/review/dispatch/implement/
+codex-implement) **and** `settings.overlay.json`. A stale reference in any
+one file will silently skip RTK for whichever subagent runs it.
+
+## Preferred command shapes in Hiskens projects
+
+These recommendations are baked into `templates/trellis/worktree.yaml`'s
+commented `verify:` block.
+
+### Python tooling
+
+| Tool | Preferred form | Why |
+|---|---|---|
+| ruff | `rtk ruff check .` / `rtk ruff format --check .` | RTK compresses ruff output; ruff has a global binary so no uv wrapper needed. |
+| pytest | `uv run pytest -q` (for now) | pytest lives inside the uv-managed env (no global binary). RTK 0.37.2 does **not** unwrap `uv run` prefixes, so `rtk rewrite 'uv run pytest'` returns empty. Migrate to `rtk uv run pytest` once [rtk-ai/rtk#1405](https://github.com/rtk-ai/rtk/pull/1405) merges and is released. |
+| python (scripts) | `uv run python ...` | Same `uv run` gap as pytest; RTK passes through. |
+
+### Shell / VCS (hook-rewritten transparently)
+
+`git diff`, `grep`, `ls`, `find`, `cat`, `curl`, `wc`, `gh` → all
+automatically rewritten by `rtk hook claude` when the hook fires. No
+explicit `rtk` prefix required in agent docs.
+
+## Verify-block rationale (`templates/trellis/worktree.yaml`)
+
+The overlay ships `verify:` commented rather than active because Hiskens
+`dev_types` includes non-Python flavors (matlab, both, trellis, test,
+docs). Forcing `rtk ruff` active would break MATLAB-only or docs-only
+projects that don't install ruff. Project maintainers uncomment the block
+matching their dev_type at `trellis init` time.
+
+The `# Fallback` block with raw `uv run ruff` exists for projects that
+haven't installed RTK yet — they can still run the Ralph Loop by
+swapping to the fallback lines.
+
+## Upstream dependencies to watch
+
+| Upstream | Impact | Action |
+|---|---|---|
+| [rtk-ai/rtk#1405](https://github.com/rtk-ai/rtk/pull/1405) "feat: add uv run support" | Unblocks `rtk uv run pytest`, kills the ~1200-call/30-day uv-run gap. | On merge + release: update this doc, migrate `uv run pytest` → `rtk uv run pytest` (or `rtk pytest` if `rtk uv` handles routing) in `templates/trellis/worktree.yaml`. |
+| rtk `hook claude` API shape | Any stdin/stdout contract change would require updating all 9 hook references at once. | Subscribe to rtk-ai/rtk release notes; grep overlay for `rtk hook claude` to find all call sites. |
+
+## Maintainer checklist when updating overlay hook wiring
+
+1. Grep the overlay tree: `rg "rtk-rewrite|rtk hook" overlays/hiskens/`.
+2. Confirm all 9 hook references (8 agents + `settings.overlay.json`) point
+   to the same form.
+3. Sanity-test in a fresh project: `trellis init --overlay hiskens` →
+   trigger a subagent Bash call → `rtk gain` should show subagent-sourced
+   counts climbing.
+4. If coverage stays at ~0.2%, the hook is not firing; re-check the
+   referenced command exists on PATH.

overlays/hiskens/templates/claude/agents/check.md

@@ -9,7 +9,7 @@ hooks:
     - matcher: Bash
       hooks:
         - type: command
-          command: /home/hcx/.claude/hooks/rtk-rewrite.sh
+          command: rtk hook claude
 ---
 # Check Agent
 

overlays/hiskens/templates/claude/agents/codex-implement.md

@@ -10,7 +10,7 @@ hooks:
     - matcher: Bash
       hooks:
         - type: command
-          command: /home/hcx/.claude/hooks/rtk-rewrite.sh
+          command: rtk hook claude
 ---
 
 ## Scope

overlays/hiskens/templates/claude/agents/debug.md

@@ -9,7 +9,7 @@ hooks:
     - matcher: Bash
       hooks:
         - type: command
-          command: /home/hcx/.claude/hooks/rtk-rewrite.sh
+          command: rtk hook claude
 ---
 # Debug Agent
 

overlays/hiskens/templates/claude/agents/dispatch.md

@@ -9,7 +9,7 @@ hooks:
     - matcher: Bash
       hooks:
         - type: command
-          command: /home/hcx/.claude/hooks/rtk-rewrite.sh
+          command: rtk hook claude
 ---
 # Dispatch Agent
 

overlays/hiskens/templates/claude/agents/implement.md

@@ -9,7 +9,7 @@ hooks:
     - matcher: Bash
       hooks:
         - type: command
-          command: /home/hcx/.claude/hooks/rtk-rewrite.sh
+          command: rtk hook claude
 ---
 # Implement Agent
 

overlays/hiskens/templates/claude/agents/plan.md

@@ -9,7 +9,7 @@ hooks:
     - matcher: Bash
       hooks:
         - type: command
-          command: /home/hcx/.claude/hooks/rtk-rewrite.sh
+          command: rtk hook claude
 ---
 # Plan Agent
 

overlays/hiskens/templates/claude/agents/research.md

@@ -9,7 +9,7 @@ hooks:
     - matcher: Bash
       hooks:
         - type: command
-          command: /home/hcx/.claude/hooks/rtk-rewrite.sh
+          command: rtk hook claude
 ---
 # Research Agent
 

overlays/hiskens/templates/claude/agents/review.md

@@ -9,7 +9,7 @@ hooks:
     - matcher: Bash
       hooks:
         - type: command
-          command: /home/hcx/.claude/hooks/rtk-rewrite.sh
+          command: rtk hook claude
 ---
 # Review Agent
 

overlays/hiskens/templates/claude/settings.overlay.json

@@ -34,7 +34,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "$HOME/.claude/hooks/rtk-rewrite.sh"
+            "command": "rtk hook claude"
           }
         ]
       }

overlays/hiskens/templates/trellis/worktree.yaml

@@ -0,0 +1,78 @@
+# Hiskens Overlay Worktree Configuration
+# Overrides base `packages/cli/src/templates/trellis/worktree.yaml` for
+# scientific computing projects (Python/MATLAB). See RTK-INTEGRATION.md
+# for the rationale behind `rtk ruff` vs `uv run ruff`.
+#
+# All paths are relative to project root.
+
+#-------------------------------------------------------------------------------
+# Paths
+#-------------------------------------------------------------------------------
+
+# Worktree storage directory (relative to project root)
+worktree_dir: ../trellis-worktrees
+
+#-------------------------------------------------------------------------------
+# Files to Copy
+#-------------------------------------------------------------------------------
+
+# Files each worktree needs its own copy of. Hiskens defaults assume a
+# multi-agent workflow where worktrees run their own subagent pipeline, so
+# both `.trellis/*` workflow assets and `.claude/*` agent wiring are copied.
+copy:
+  # Environment variables (uncomment and customize as needed)
+  # - .env
+  # - .env.local
+
+  # Trellis workflow config and shared scripts
+  - .trellis/.developer
+  - .trellis/scripts
+  - .trellis/spec
+  - .trellis/templates
+  - .trellis/config.yaml
+  - .trellis/.link-state.json
+
+  # Claude Code subagent wiring (hooks + commands + agents + skills)
+  - .claude/hooks
+  - .claude/commands
+  - .claude/agents
+  - .claude/skills
+
+#-------------------------------------------------------------------------------
+# Post-Create Hooks
+#-------------------------------------------------------------------------------
+
+# Commands to run after creating a worktree (cwd = worktree root).
+# Executed in order; abort on first failure.
+post_create:
+  # Python projects: sync uv environment
+  # - uv sync
+
+  # MATLAB projects: no-op (MATLAB uses global toolbox install)
+
+#-------------------------------------------------------------------------------
+# Check Agent Verification (Ralph Loop)
+#-------------------------------------------------------------------------------
+
+# Commands to verify code quality before the check agent can finish.
+# Ralph Loop runs these; all must pass (exit 0) to allow completion.
+# Leave empty to trust the agent's own completion markers.
+#
+# RTK integration notes (see RTK-INTEGRATION.md for details):
+# - `rtk ruff` compresses ruff output through the RTK hook and works out of
+#   the box because ruff ships a global binary. Preferred for Hiskens projects.
+# - `rtk pytest` requires a global pytest binary; most Python projects only
+#   have pytest inside the uv-managed env. Keep `uv run pytest` until
+#   rtk-ai/rtk#1405 ("uv run support") lands and is released.
+verify:
+  # Python projects (uncomment):
+  # - rtk ruff check .
+  # - rtk ruff format --check .
+  # - uv run pytest -q
+
+  # MATLAB projects (uncomment):
+  # - matlab -nodesktop -nosplash -batch "run('tests/runtests.m')"
+
+  # Fallback if rtk is not installed:
+  # - uv run ruff check .
+  # - uv run ruff format --check .