Refresh RTK integration: migrate to rtk hook claude + ship Python worktree.yaml#1
Merged
Merged
Conversation
The 8 subagent frontmatters and settings.overlay.json referenced a legacy `$HOME/.claude/hooks/rtk-rewrite.sh` shell wrapper that no longer ships with rtk (0.37.2 replaced it with a direct `rtk hook claude` binary command). Without the script file on disk, PreToolUse hooks fail silently and every subagent Bash call runs raw — measured via `rtk discover` as 0.2% RTK coverage across 12357 commands in the last 30 days. Aligns overlay hook targets with the current global settings.json pattern (`"command": "rtk hook claude"`) used outside subagents. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Base Trellis ships a pnpm-oriented worktree.yaml template that leaves Python projects to hand-craft verify commands — in practice every Hiskens project ends up rewriting the same `uv run ruff check .` block. This overlay template lands at `.trellis/worktree.yaml` via the WORKFLOW_OVERLAY_TARGETS mechanism (applied after base template during `trellis init` / `trellis update`). It ships Hiskens-correct defaults: - `copy:` list expanded for multi-agent worktrees (scripts/spec/agents/ hooks/skills all copied per worktree so subagent pipelines work). - `verify:` block uses commented RTK-preferred examples for Python (`rtk ruff`) and MATLAB, with `uv run ruff` as fallback. Left commented because Hiskens dev_types include non-Python variants. - `rtk ruff` is preferred because ruff has a global binary and RTK compresses its output. `uv run pytest` stays because pytest lives in the uv-managed env (no global binary); will migrate to `rtk uv run pytest` after rtk-ai/rtk#1405 lands. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Captures the current RTK hook contract (`rtk hook claude`), the migration history away from the legacy `rtk-rewrite.sh` wrapper, the rationale behind the commented verify: block in the new worktree.yaml template, and the upstream rtk-ai/rtk#1405 dependency that will unblock `rtk uv run pytest` once released. Sits next to MAINTENANCE.md as maintainer-facing docs (not shipped to consumer projects via the overlay template pipeline). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
SDDKKK
added a commit
that referenced
this pull request
Apr 23, 2026
Adds two new pitfalls to fork-sync-guide.md's Common Pitfalls section, captured from the 2026-04-23 Anhui_CIM sync: - Pitfall 8: Syncing downstream from a stale fork main. `trellis update --overlay hiskens` reads overlay files from the fork's filesystem; if the local main is behind origin/main (e.g. after merging a PR on GitHub without `git pull`), the consumer gets a stale overlay. Measured case: Round 4 shipped partial state because local main sat at ef56d94 while origin/main had advanced to b8a4df7 (PR #1 merge). - Pitfall 9: Trusting trellis update reports without hook-command verification. A single hook command line can silently stay on the old `/home/<user>/.claude/hooks/rtk-rewrite.sh` absolute path after an incorrectly keep-local triage decision. Added a 2-second `grep -HnE '^\s*command:' .claude/agents/*.md` sanity check that catches this + the inverse (unexpected command lines). Also adds two entries to the Anti-checklist: don't skip `git pull --ff-only` before downstream sync; don't ship without grepping agent command lines. Task directory `.trellis/tasks/04-23-downstream-sync-round4/` included with full execution log of Round 4 + 4b. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
settings.overlay.json) from the legacy$HOME/.claude/hooks/rtk-rewrite.shwrapper to the currentrtk hook claudedirect-binary API. The wrapper stopped shipping with rtk 0.37.x, so every subagent Bash call in Hiskens projects has been running raw —rtk discovermeasured 0.2% coverage across 12357 commands in the last 30 days.worktree.yamlatoverlays/hiskens/templates/trellis/worktree.yaml. It lands in consumer projects via theWORKFLOW_OVERLAY_TARGETSmechanism (configurators/index.ts:L301-303), overriding the base pnpm-oriented template. Comes with commentedrtk ruff/uv run pytestverify examples for Python and a MATLAB variant; leaves the block commented so non-Python dev_types (matlab, trellis, test, docs) aren't broken.overlays/hiskens/RTK-INTEGRATION.mdas a maintainer-facing doc next to MAINTENANCE.md. Records the hook API migration history, preferred command shapes (rtk ruffpreferred;uv run pyteststays until feat: add uv run support rtk-ai/rtk#1405 lands), the rationale for keepingverify:commented, and a maintainer checklist for future hook-wiring changes.Why
The 0.2% RTK coverage was traced to the missing
rtk-rewrite.shreferenced in overlay-shipped subagent frontmatters. Fixing only the hook API (commit 1) closes that gap for every existing and future Hiskens project. The worktree.yaml template (commit 2) removes the per-project need to rediscover theuv run ruffpain — newtrellis init --overlay hiskensruns get Python-correct defaults out of the box.The
uv run pytest→rtk pytestmigration is intentionally deferred. pytest has no global binary in typical uv-managed Python projects, and rtk 0.37.2 does not yet unwrapuv runprefixes (open PR rtk-ai/rtk#1405 addresses this). RTK-INTEGRATION.md captures the follow-up action once that lands and is released.Test plan
rtk gainshould show subagent-sourced counts climbing (previously flat).trellis init --overlay hiskensin a scratch directory and verify.trellis/worktree.yamlmatches the new template (overlay layer winning over base).trellis updateon an existing Hiskens project and confirm the worktree.yaml diff is shown for review (non-destructive, per update.ts pipeline).grep -r "rtk-rewrite" overlays/hiskens/returns empty.rtk hook claude:grep -r "rtk hook claude" overlays/hiskens/ | wc -lshould equal 9.🤖 Generated with Claude Code