Symlink the vendored rule files instead of re-syncing copies by hand
Nobody has claimed this yet.
- Dominant language
- Shell
- Stars
- 267
- Forks
- 23
- Avg merge
- 2d 6h
- Merged PRs (30d)
- 12
Description
Summary
The suite keeps shared material in sync three ways. One of them, byte-identical vendored copies, is the only one that
depends on a person remembering to re-sync, and it covers the most files. #184 already proved the alternative works. I
would like to reduce three mechanisms to two.
The companion issue on config-loading duplication (#203) is independent of this one; either can land first.
The three mechanisms
| Mechanism | Used by | Sync burden |
|---|---|---|
| Symlink, dereferenced at install | scripts/han-config-dir.sh |
none |
| Vendored byte-identical copy | config-rule.md, collaborative-stop-rule.md, yagni-rule.md, evidence-rule.md |
manual, untested |
| No copy; declare a dependency | readability-rule.md, writing-voice.md |
none |
The middle row is 22 copies of 4 files, about 3,150 duplicated lines:
config-rule.md 151 lines x 12 copies = 1812
yagni-rule.md 146 lines x 4 copies = 584
evidence-rule.md 120 lines x 4 copies = 480
collaborative-stop-rule.md 137 lines x 2 copies = 274
Nothing tests that the copies match the canonical file.
There is no drift today
I checked all 22 copies against their canonical files on main: every one matches. I also walked
han-coding/references/config-rule.md against han-core's across every commit that touched the canonical file, and
they match at every point.
So this is not a bug report. It is a request to remove a manual invariant that holds only because maintainers keep
remembering it. The cost shows up in release notes: "the vendored rule files re-synced with their canonical copies" and
its variants appear 12 times in the v5.4.0 section of CHANGELOG.md.
Why symlinking works
55bdb1d (#184) records it:
Installation copies the symlink target as a regular file, so the script ships without any plugin depending on another
to reach it.Verified across all 12 plugins in default mode, and end to end through a GitHub-source marketplace install.
I confirmed the install side independently: on a VM,
.claude/plugins/cache/han/han-communication/1.2.0/scripts/han-config-dir.sh is a regular file. A skill reads a real
file either way.
Linting is not an obstacle
Prettier on its own refuses an explicitly specified symlink and exits 2, and a .prettierignore entry does not suppress
it. But prek never hands a symlink to a hook. In a scratch repo tracking one symlinked .md whose target was
deliberately misformatted, prek run --all-files reported prettier ... Passed and left the target unchanged. No hook
change, exclude: rule, or ignore file is needed. The canonical file is still linted under its own path.
Why the markdown was never symlinked is not recorded anywhere: cfdfff7 carries a subject line and no body, and
CONTRIBUTING.md has no vendoring section. The two conventions landed two months apart, in #143 and then #184.
Proposal
- Replace the 22 vendored
references/*.mdcopies with relative symlinks to their canonical files. No lint
configuration changes. - Add a test for what the existing hooks miss.
check-symlinksanddestroyed-symlinksalready fail a dangling link
or one flattened into a regular file. Neither can see coverage (a plugin that should carry a reference and
carries nothing is not a symlink, so no symlink hook looks at it) or target correctness (a link that resolves,
but to the wrong file). - Record the convention in
CONTRIBUTING.md.
Open questions
- Is dereference-on-install guaranteed or incidental? Worth settling first. #184 verified it through a
GitHub-source marketplace install and my VM agrees, but I cannot find it stated in Claude Code's docs. If it is
incidental, a symlinked reference could one day ship dangling, which fails worse for a reference than for the script:
the script's probe carries a2>/dev/null || echofallback and areferences/*.mdlink has no equivalent. The repo
side is already covered bycheck-symlinksanddestroyed-symlinks; it is packaging I want confirmed. - Should some of these use the invoke-a-guidance-skill mechanism instead?
readability-rule.mdand
writing-voice.mdare not copied at all; consumers declare ahan-communicationdependency and invoke
readability-guidance, which resolves them through its own${CLAUDE_PLUGIN_ROOT}. That is a separate discussion,
filed as #203. It does not compose forconfig-rule.mdin any case, sincereadability-guidanceitself
points atconfig-rule.mdby relative path intohan-communication's own vendored copy. - Does non-Claude packaging dereference the same way? I have only checked the Claude Code side. #172 is doing Pi
parity and touches.agents/plugins/marketplace.json, so it will likely reach the answer first.
Before I start
@mxriverlynn happy to take this on, including the first open question, if you have no objections. Checking first since
it touches every plugin, and you may have ruled symlinks out here for a reason that is not written down.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading #184, scripts/han-config-dir.sh, and the existing check-symlinks and destroyed-symlinks hooks, then verify dereference behavior for Claude and non-Claude packaging. Review the 22 references/*.md paths and CONTRIBUTING.md; done means the copies are replaced consistently, coverage and target correctness are tested, and the convention is documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- shell
- Domain
- build-system, documentation
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100