v3.0.1: the consequence we filed under “if a consumer asks”

Released 2026-09-15. One fix, shipped the same day as the major it repaired.

What we were trying to fix

3.0.0 split the kit into two plugins that ship from one tree, and the two plugin directories reached that tree through git symlinks. On Windows, git has no privilege to write a symlink unless the machine is in Developer Mode, so each link arrived in the checkout as a small text file holding the path it was supposed to point at. The Claude Code loader discovers a skill by finding a directory with a SKILL.md inside it. It found neither. The first Windows install after the release loaded zero skills, and nothing said why: the files were all there, they were simply the wrong kind of thing.

What we decided

The plugin trees stop being links and become generated copies (ADR 0017). python3 scripts/host-adapters.py build writes both halves out of the one source under skills/, scripts/ and hooks/, and its check subcommand refuses a drifted copy, an orphan, a committed symlink or a file whose mode does not match its source. The cost is that every change to a shipped file now lands as two diffs, the source and its copy. The gate is what makes that bearable: a forgotten build fails CI by name rather than shipping a plugin one commit behind its own tree.

What got cut

The alternative was to keep the symlinks and document Developer Mode as a prerequisite. That is a prerequisite on the consumer for a convenience of ours, which is the wrong way round, and it would have stayed invisible until the next Windows user hit it.

What bit us

ADR 0016 had already predicted this exact failure in its own Consequences, and filed the remedy under “if a consumer asks”. A consumer asked on the day of the release (#619).

A consequence a decision record names and then leaves optional is a decision to ship the failure and wait for a report, and the report always comes from whoever had the worst day. If a record can describe the breakage precisely enough to write it down, it is already precise enough to gate.